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PREFACE 


The MRX/OS Control Program and Data Management 
Services are discussed in two separate documents, 
each designed for a specific type of input/output 
(1/O) level user. The Basic Reference manual contains 
information at the logical 1/O level of processing, 
where the blocking and deblocking of data is done for 
the user. This document, the Extended Reference 
manual, is designed for the block and physical !/O 
level user. Block 1/O level processing recognizes no 
logical records; therefore, all data is read or written as 
a data block. The physical I/O level of processing 
allows the user to do his own processing of data. 


Chapter 7 of this document contains all the macros 
required for block and physical I/O level processing. 


Appendix B contains the expansions of these macros 
with the standard system suffixes listed. 


Related information may be found in the following 
documents. 


o MRX/OS Control Language Services, 
Extended Reference 


o MRX/OS Contro! Program and Data 
Management Services, Basic Reference 


o MRX/OS Assembler Reference 
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ENVIRONMENT 


The logical, block and physical input-output facilities 
and contro! program services described in this manual 
are all available on the MRX/OS nominal system.” All 
except for those flagged are also available on the 
MRX/OS minimal system.t Since MRX/OS is a 
disc-resident system, a minimum of one disc drive is 
required for the system disc pack. 


DESCRIPTION 


The services described in this manual are those 
provided by the central part of the operating 
systemtt. Access to these services, which are mainly 
concerned with input/output processing, is through 
system macro instructions. 


*The nominal system has a minimum main storage size of 
24K bytes, including a system region of 10K bytes. 


tThe minimal system has a minimum main storage size of 
16K bytes, including a system region of 8K bytes. 


tt Other operating system services, such as job control, link 
editing and library utilities, are described in separate 
manuals. 


1. INTRODUCTION 


INPUT/OUTPUT LEVELS 


GENERAL 


An Assembly Language programmer may code his 
input/output implementation at three different 
levels: the logical, block, and physical levels. The 
logical level is processed by the Data Management 
system while the block and physical levels are 
processed directly by the system’s basic input/output 
routines (upon which Data Management depends). 


The logical level, the highest level, is the easiest to 
use. The block level provides greater flexibility but is 
still dependent on the standard system data file 
structures. The physical level is the most involved, 
regarding coding, but provides the greatest flexibility, 
including independence from the system’s file 
structures. 


LOGICAL INPUT/OUTPUT 


Logical input/output coding (described in the Control 
Program and Data Management Services, Basic 
Reference and in Section 2 of this book) is normally 
employed in situations where no special handling of a 
condition such as end-of-file is required and the 
amount of available storage space is not especially 
restricted (though careful coding will still enable the 
programmer to economize on storage space). The 
chief advantage of logical input/output is the 
simplicity of coding for most common input/output 
applications. 
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BLOCK INPUT/OUTPUT 


Block input/output coding (described in Section 3) 
enables the programmer to create an object program 
smaller than would result from logical input/output, 
since the large general-purpose GET/PUT subroutines 
are not included. When the user’s input/output 
application is limited to a certain particular type of 
operation, block input/output produces a smaller, 
more efficient program but involves more work in 
writing the code. Block input/output is also necessary 
in the case where some special handling of abnormal 
conditions is required. 


PHYSICAL INPUT/OUTPUT 


Physical input/output coding (described in Section 4) 
is used where the user desires to create and process 
his own special external data structures for some 
special application, or where some special 
input/output device such as a plotter is being used. 
(The standard system files may also be processed by 
physical input/output if desired, though this would 
rarely be done in practice.) 


IMPLEMENTATION METHOD 


Ultimately, whether logical, block, or physical I/O is 
being used, all input/output implementation is 
performed by the system’s input/output drivers. The 
basic mode of communication with the drivers is 
always the same; it involves supplying them with a 
“command program”, which is a contiguous group of 
command control blocks, each one calling for the 
execution of a specific I/O operation. 


The physical input/output user must create these 
command programs himself with physical 
input/output macros, and issue do input/output 
macros which instruct the system to execute them. 
The block input/output user, on the other hand, 
simply codes the appropriate block input/output 
macro; in this case the system builds the command 
program and executes it. At the logical input/output 
level (data management) the system performs certain 
pre- or post-processing of data connected with the 
logical data file structure before or after it passes 
control to the block input/output level for 
implementation of the actual data transfer. 
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The structure of records, labels, and files is discussed 
in connection with their use. The Control Program 
and Data Management Services, Basic Reference 
discusses the general data structures. This manual 
gives the specific description of labels and tables. 


FILES AND RECORDS 


Data Management supports records that have the 
common stored data format, which include logical 
record headers and may include space headers in each 
block of data. If the block I/O user elects to use the 
common stored data format, he must specify CSD = 
YES on the Control Language //DEFINE card to 
allocate a block size sufficient for the required 
headers. The control information (record headers and 
space headers) is managed by Data Management for 
logical 1/O users. However, block 1/O level or physical 
1/O level users must generate or process the control 
information if the common stored data format is 
used. The common stored data format is used only 
for data located in mass storage; thus data stored on 
unit record devices does not have this format; and 
this format is not applied to such data by the block 
1/O level READ function (Section 7, Macros). 


Records may be variable length or fixed length 
limited only by file organization and devices; that is, 
only fixed-length recorcls can be used for unit record 
devices. 


Three file organizations, which produce a variety of 
applications, are available for the user: sequential, 
relative, and indexed. At the logical I/O level, two 
access methods are provided — sequential and 
random. At the block I/O level, each access is by 
specified block (random) or by implied next block 
(sequential, by adding one to the access count). 
Sequential access is provided for all three file 
organizations; however, random access is limited to 
relative or indexed files. 


2. DATA STRUCTURES 


A more detailed discussion of file and record 
structures is in the Control Program and Data 
Management Services, Basic Reference. 


LABELS 


Two types of identification are associated with a disc 
pack or tape reel: external (such as a sticker) and 
internal (labels). This section is concerned with the 
internal identification, namely the labels. 


The internal identification serves two purposes. 


1. Labels protect files from careless mistakes 
resulting from the user's disregard for external 
labeling. 


2. Labels specify the location of data on files and 
store variable file information. 


Tapes are identified by both volume and file labels; 
the disc files have volume labels and central and/or 
pack catalogs. 


TAPE LABELS 


The MRX 40 and 50 Systems have two types of tape 
labels: volume labels and file labels. 


The volume label is found at the beginning of a tape 
reel and the file label at the beginning of a file. Tape 
marks separate files and their associated labels on a 
tape reel. 


The volume label (Figure 2-1) is identified by the 
characters, VOL, found in the first three positions. 
The volume label number is always 1 for 
compatibility with IBM. The volume serial number 
occupies positions 4 through 9 and identifies the 
volume; and a unique owner name and address code 
identifies the installation. 


ees 0 
STATE OF VOLUME 1 
POINTER TO VTOC (VOLUME 2 


TABLE OF CONTENTS) ONLY ON 
CONVERTED IBM PACKS 
DEVICE TYPE oe 


PACK CATALOG ADDRESS 


OWNER 
(1-56 BYTES EBCDIC) 


Figure 2-1. Standard Tape Volume Label 


The standard tape file label (Figure 2-2) provides 
information concerning the user’s file such as creation 
and expiration dates, file label number, file name, and 
sequence number. 


The label identification field identifies the type of 
standard label with a three letter abbreviation. Three 
types supported by the system are header labels 
(HDR), end-of-file labels (EOF), and end-of-volume 
labels (EOV). The file serial number found in 
positions 22-27 is identical to the volume serial 
number in the volume label. The volume sequence 
number identifies the order of the volume of data 
records in a multi-volume logical file. The block 
count provides the number of physical records 
written in a file at creation. 


DISC LABEL 


Disc files must be labeled with volume and actual file 
identification (Figure 2-3). The disc pack volume 
label is written by the Pack Initialize Utility Routine 
(MRX/OS Utility Programs Reference). The volume 
label identifies the volume; gives the state of the 
volume — unrestricted (0), restricted (1), or locked 
(2), — device type, owner; and gives the starting track 
address of the pack catalog for this volume. The 
actual file identification is found in the disc catalogs. 
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HDR 


LABEL IDENTIFICATION ~<+——-+ EOF 


FILE LABEL NUMBER 


FILE NAME 


FILE SERIAL NUMBER 


VOLUME SEQUENCE NUMBER 


CREATION DATE 


EXPIRATION DATE 


BLOCK COUNT 


Figure 2-2. Standard Tape File Label 


EOV 


BYTE 


VOLUME LABEL NUMBER 


VOLUME SERIAL NUMBER 


OWNER NAME 
AND 
ADDRESS CODE 


Figure 2-3. Disc Label 


DISC STORAGE CATALOGS 


The space management routines, in performing their 
functions, maintain the central catalog and pack 
catalogs on disc. The pack catalog, existing on each 
volume, contains an entry for each file occupying 
space on the volume. The entry identifies the file and 
describes the space occupied by the file. 


The pack catalog entry is generally divided into the 
following three elements, each having the form of a 
common stored data format. 


e Name element, to identify the file 


@ Attribute element, to detail various 
characteristics of the file 


e Space element, to define the space occupied 
by the file 


The central catalog, existing once for a system, 
contains an entry for each file cataloged in the 
system. The entry identifies the file and describes the 
volumes occupied by the file. The central catalog also 
consists of three elements: 


@ Name element, to identify the file 


e Attribute element, to detail characteristics 
of the file 


@ Volume element, to define the volumes 
occupied by the file 


Allowance is made in the catalog structure for 
overflow from a pack catalog space element or central 
catalog volume element. These elements are Known as 
element continuations: space element continuation 
and volume element continuation. 


Tables 2-1 through 2-4 explain format of the four 
basic elements and the two element continuations. At 
the beginning of each table is an illustration of the 
specific element format. Appendix A _ contains 
detailed discussion of the pack catalog and central 
catalog formats. 
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Table 2-1. Name Element Format 


Standard Control Bytes 


Next Name Element 


oo | 


Previous Name Element 


Name Length | 


File Name and Qualifier 


Number of Pointers 


Pointer Identification 


40 Pointer 
42 Pointer Identification | 
44 Pointer 
46 Pointer Identification | 
48 7 Pointer 


Description 


Data type (binary) 
01 User data 
10 System data 


11 Both user and system data 


Reserved, always 0000, 


Count of length bytes, always 105 


Relative record number within block, with value 0 to m-1 for m records 


Length bytes, giving length of the record (in bytes) with the measurement being exclusive of the control bytes 


Thread to the next name element (in collating sequence). This thread is expressed in a BBR format, where BB 
is the relative block number (value 1 to n for n blocks) and R is the relative record number (value 0 to m-1 for 
the next name element's position within block BB. BBR=0 for the thread in the last name element of the chain. 


Thread to the previous name element within the catalog file. BBR=0 for the first name element of the chain. 


Name length, giving the count of bytes in the File Name and Qualifier field. The total count must 
be even and not exceed 26. 
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Table 2-1. Name Element Format (Continued) 


Bytes Bit Description 


11-36 File Name and Qualifier, containing a file name consisting of a maximum of 17 EBCDIC characters (alphabetic, 
numeric, and dash), a period separator, and a qualifier consisting of a maximum of eight alphanumeric charac- 
ters. For name elements related to a system catalog file, the EBCDIC requirement is lifted. 


37 Ce Number of element pointers which follow within the name element. 


38,42, Pointer identification, expressed in hexadecimal within one byte and identifying the pointer, where * denotes 
46 pertinent name elements within an entry in the pack catalog, and ** denotes pertinent name elements within 
an entry in the central catalog. Other pointers are pertinent in both the pack and central catalogs. 


00 Null pointer 

10 Pointer to attribute element 

20* Pointer to space element 

30** Pointer to volume element 

40** Pointer (from the indexed file’s name element) to the name element of the information file 

41** Pointer (from the information file’s name element) to the name element of the indexed file 
50 Pointer (from the tower paired file’s name element) to the name element of the upper file 

51 Pointer (from the upper paired file’s name element) to the name element of the lower file 

60* System pointer (from the pack catalog name element describing the pack catalog) to the 


chain of available entry blocks within the pack catalog 


61* System pointer (from the pack catalog name element describing the pack catalog) to the 
chain of available continuation blocks within the pack catalog 


70** System pointer (from the central catalog name element describing the central catalog) to 
the chain of available entry blocks within the central catalog 


TA System pointer (from the central catalog name element describing the central catalog) to 
the chain of available continuation blocks within the central catalog 


80** System pointer (from the name element of a SYSIN or subordinate scratch or temporary 
file) to the name element of the next chronologically sequenced scratch or temporary file. 
Scratch or temporary files are cataloged like any other file, in that they are entered by 
collating sequence into the main chain of existing files. In addition, the scratch or temporary 
file is linked in a secondary chain to the pertinent SYSIN entry through use of the forward 
system pointer (identification of 80) and backward pointer (identification of 81). 


31** System pointer (from the name element of a scratch or temporary file) to the name element 
of previous scratch or temporary file or to the SYSIN entry at the front of the secondary 
chain 


Pointers (in BBR format) to the pertinent elements previously described. 
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Paired index (P!) 
0 Upper file 


Table 2-2. Attribute Element Format 


Standard Control Bytes 


Spread 


Block Size 


Record Length 


Relative Key Position 


’ Key Size | 


Highest Block Written 


16 
18 Reserved 
20 
22 
Modification Security Code 
24 
26 
Offset 
28 


Bit Description 


Control bytes (defined in Table 2-1) 


Paired file flag. If PF=1, file is paired 


1 Lower file 
2 Write verify (WV) 
0 No write verify 
1 Write verify 
3,4 File type (FT) 
oo Permanent 
01 Scratch 
10 Temporary 
11 Work 
5-7 File organization (FO) 
000 General 
001 Indexed 


Byte 


©& 
~ 


& 
to 


= 
N 


- 
N 


Table 2-2. Attribute Element Format (continued) 
Description 


010 . Relative 
100 Sequential 


111. Information (for indexed file) 


Central catalog (CF) 
0 File is uncataloged 


1 File is cataloged 


Comrnon stored data format (CD) 
0] Not common stored data format 


1 Common stored data format 


Control character (CC) 
0 ANS! contro! characters 


1 Native device control characters 
Spread factor for indexed files (SPREAD) 


Block size (in bytes) of data block 


Record tength (in bytes) of a record within a data block 


Relative key position; pointer to the primary key in the data portion of a record. Position O refers to the first 
byte following the control bytes. 


Key size (in bytes) of the primary key 


Highest block written, relative block number for the last block written in the file 


Reserved 

Modification security code 

Offset; lower limit of relative record number at the time a relative file is created or, for a sequential file, the 
relative block number for the first block of the highest volume written. In the information file’s attribute 


element for an indexed file, the first two bytes have the count of directory blocks that have been allocated. 
The other two bytes have the count of index blocks. 
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Table 2-3. Space Element and Space Element Continuation Format 


Standard Control Bytes 


18 Segment Count 

20 Segment Sequence Number 
22 Track Address 

24 Track Count 


*One per segment 


Space Element 


Standard Control Bytes 


Continuation of Space Element 


Previous Space Element — 


Segment Sequence Number 


Track Address 


Track Count 
tOne per segment 


Space Element Continuation 
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Table 2-3. Space Element and Space Element Continuation Format (Continued) 


Description 


Control bytes (defined in Table 2-1) 


Continuation of space element, a thread (in BBR format) which points to the next space element continuation 
for a file 


Previous space element is a thread (in BBR format) which points to the previous space element. 


if LV=1, this is the last volume for a file 


If CE=1, a space element continuation exists 


If CB=1, each segment lower boundary is on a cylinder boundary 


Not used 


Segment count, a count of space elements used by the file on this volume 


Segment sequence number, giving relative segment number for each segment (shows relation to segments 
existing on same or separate volumes) 


Track address relative to beginning of segment. (Al! physical disc addresses are expressed in terms of track 
number rather than cylinder and track within a cylinder.) 


Track count of tracks in segment 


*Byte position(s) unique to space element continuation table. 


Table 2-4. Volume Element and Volume Element Continuation Format 


Standard Control Bytes 
4 Continuation of Volume Element 
6 esses Zee wo | CE 
8 Segment Count 
10 Volume Count 
12 
14 Voiume Serial Number 
16 
18 File Name Entry in Pack Catalog ; 
20 Device Type 


Reserved 


*One per volume 


Volume Element 


Standard Controi Bytes 


Continuation of Volume Element 


j mo | ce | 


Volume Serial Number 


File Name Entry in Pack Catalog 


Device Type 


Reserved 


tOne per volume 


Volume Element Continuation 
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Table 2-4, Volume Element and Volume Element Continuation Format (Continued) 


Description 
Control bytes (defined in Table 2-1) 


Continuation of volume element, a thread (in BBR format) which points to the next volume element continuation 
for a file 


Modified volume descriptions. If MD=1, central catalog is created and modified volume descriptions are 
included, 


If CE=1, volume element continuation exists 
Segment count 
Volume count 


Volume serial number 
File entry in pack catalog, a pointer to the file’s entry in the specified volume’s pack catalog (BBR format) 


Device type (00, ¢ for MEMOREX 3664 Drive) 
If HW=1, highest volume written 


Reserved 


*Byte position(s) unique to volume element continuation table. 
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TABLES 


Tables are primarily for storage information that is 
easily referenced. The Data Management system has 
two primary tables for information reference: 


e File Description Table (FDT) created by 
OPEN 


e Buffer Description Table (BDT) created by 
DEFSF, DEFRF, or DEFIF 


FILE DESCRIPTION TABLE 


A File Description Table (FDT) is built dynamically 
during a job’s execution time in the user area of 
memory. An OPEN request causes an FDT to be 
built, and a CLOSE request releases the FDT space. 
The FDT is 60 bytes in length. The portion of the 
FDT common to all files is 40 bytes in length, and 
the remainder of the FDT which is device dependent 
is 20 bytes in length. 


The FDT is linked with block I/O requests through an 
8-byte identification field; the identification field in 
the FDT and the block !/O request must match. The 
FDT contains a unit table ordinal through which !/O 
control routines find the unit table and execute the 
1/O request. Parameters in the FDT protect users 
from overlapping each other’s area on a shared device. 
Table 2-5 gives the locations of the different 
information fields of the FDT. Tables 2-6 through 2-8 
give the device-dependent fields of the FODT. 
Manipulation of FDT’s in the user partition is 
discussed in Control Language Services, Extended 
Reference. 
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BUFFER DESCRIPTION TABLE 


A Buffer Description Table (BDT) is created by the 
file definition macros (DEFSF, DEFRF, and DEFIF). 
This main-memory table is used by the GET/PUT 
logic to manage buffers and control logical records. 
The BDT is responsible for recording location of 1/O 
buffer(s) and record areas. 


A BDT is created for each file organization: 
sequential, relative, indexed. The three BDT format 
tables follow with the appropriate field descriptions 
(Tables 2-9 through 2-11). 


Table 2-5. File Description Table Format 


-10 Reserved 


8 LOA 


4 Label Ordinal 


2 PFL 


NFL 


identification 


US | eB} uo] | sF| Last Block I/O Function 


Current Block Number . 


| enn 
22 Block Size 

24 Current CW Pointer 

26 Status 

28 RC 


30 Device Dependent Fields* 


*Refer to appropriate clevice table (Tables 2-6 through 2-8). 


Description 
Reserved 
Length (in bytes) of FDT (LOA) 
Ordinal bit (OB) 
0 Label ordinal points to central catalog 


1 Label ordinal points to Control Language job file 
Label ordinal indicates the position of the label in the central catalog or the Control Language job file. 


Previous FDT address (PFL) 
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Table 2-5. File Description Table Format (Continued) 


Description 


Next FDT address (NFL) 


User bit (UB) reserved for emulator set to zero when FDT is built 


Freeze flag (FRE) 


0 File is not frozen 
1 File is reserved for a recycle of outstanding queue entry block (QEB) 


Native character set flag (NC). If NC=1, first data byte is the command code. 


Device type 


File identification 


Common stored data format bit (C) 
Oo Not common stored data format 


1 Common stored data format 


Usage flag (US) 


00 Input 
01 Update 
10 Output 


Bypass flag (B) 
0 No bypass 
1 Bypass, READ goes to EOF and WRITE is a NOP 


Update flag (UD) 
10) No update 
1 Update 


Lockout flag (L) 
0 No lockout 


1 Close with lock 


Sequential file (SF) 
0 Not sequential 


1 Sequential 


Last function processed in block 1/O 


Block number after last function processed. If zero, current block number is unknown. 


End condition bit (END) indicates the sensing of an end condition: EOF, EOA, or printer carriage channels 
9or 12. 


eel 


Return code 


Tabie 2-5. File Description Table Format (Continued) 


Description 
Error recovery processing flag (ERP) 
0) Call error recovery when errors encountered 
1 Do not call error recovery for errors 
FDT restore (FR) 
0 FDT not restored 
1 FDT restored 
Hold up flag (H) 
10) File not in recovery 
1 File in error recovery and following requests are held up until recovery complete 


Block 1/O internal flag (BB); set by block 1/O to indicate that a RESET macro has passed through the file. 
Bit is reset by driver. 


Tag for cammand word (CW) address pointer 

Byte size (or maximum size) of each record 

A pointer to the current or last CW executed by this file 
Status of fast 1/O operation 


Residual count (RC): the difference between bytes requested and bytes received 


The device dependent portion of the FDT begins at byte 30. 
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Table 2-6. Disc Device Format 


WF | DF | Reserved Number of Residual Blocks 


Highest Block Written 


Relative Block Number 


Blks/Track ‘a Gap 


Next Segment Link 


44 UORD Reserved 


Number of Contiguous Tracks 


Beginning Track Number 


*Extent 


Bit Description 


Reserved 


Paired file flag (PF) 
Oo Not paired 
1 Paired file 


Paired file indicator (PA) 
0 Upper portion of track used for this file 


1 Lower portion of track used for this file 


Write check flag (WF) 
¢] No write check 


1 Write check of all writes 


Disc driver flag (DF) 


Reserved 


Residual block number, the number of blocks remaining to be up for a multiblock read request which crosses 
tracks 


Highest block number written for volume now mounted 


Relative block number (calculated from beginning of file) of first block on presently mounted volume 


Number of records on a disc track (BLK/TRACK) 


Gap in bytes between records for pack rotational speed variation 


42-43 


ee 
N: 


on w N) ° 
~“ 


Next segment link (extent address) 
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Table 2-6. Disc Device Format (Continued) 
Description 
Unit table ordinal (UORD) which indicates the unit table to which this segment is related 
Reserved | 
Number of contiguous tracks 


Beginning track number for this extent (0-3999) 
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Table 2-7. Magnetic Tape Device Format 


32 Sense 


Relative Block Number 


UORD ALT ORD 


Volume Number 


Description 


o 
< 
pes 
@ 
w 
+ 


Sense bytes of the unit at the time of the last error 


Relative block number (calculated from beginning of file) of first block on presently mounted volume 


Current unit table ordinal (UORD) 


Unit ordinal of alternate tape (ALT ORD) 


Volume number 


47 Label processing flag (LP) 
0 No label processing. complete 
1 Label processing complete 


Tape mark fiag (TM); a tape mark precedes the first data record on the tape 


Offset (O), an alternate unit 


i ina 
a 
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Table 2-8. Unit Record Device Format 


Description 


Sense byte of the unit at the time of last error 


Unit table ordinal (UORD) 
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Table 2-9. Buffer Description Table Format for Sequential Files 


0 «GET/PUT Address 
2 | ne | FTYP s LABL | am | RT | Blocking Factor 
4 Block Size 
, ne Record Size 
8 S TAG GP MOD hese, S TAG RA 
10 a "ReCOrE Area Address 
12 ee ee 


File Identification 


S TAG SA 

22 __ Save Area Address 
24 Error Offset 
26 a S TAG RAP 
28 Record Address Pointer 
30 

Relative Record Number 
32 
34 


Current Block Number 


Logical Record Number 


Litv] «ticle | 


Use 
42 
Work Area 
44 
46 
Move Routine 
54 
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Table 2-9. Buffer Description Table Format for Sequential Files (Continued) 


Block 1/O Packet 


Buffer 1 1/O Packet 


Buffer 2 1/O Packet 


1124 


S TAG EA 


Error Address 


114 


*Optional 


If buffer 2 is absent, bytes 90 through 93 end the BDT as follows: 


Error Address 


Description 


External address of the GET/PUT module processing this file 


Number of buffers (NB) 
(8) One buffer 


1 Two buffers 


File type (FTYP) 
00 Sequential 
01 Relative 


10 indexed 


Shared buffer flag (S). If S=1, 1/O buffers are shared with other files. 


Label processing (LABL) 
00 No labels 
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Table 2-9. Buffer Description Table Format for Sequential Files (Continued) 


Bit Description 


01 Nonstandard labels 
10 Standard labels 


Access method (AM) 
0 Sequential 


1 Random 


a a nn i ST 


Record type (RT) 
0 Fixed length 
1 Variable length 


Blocking factor, number of records per block (0-255) 


Block size (in bytes) of the I/O buffer(s), size must include record headers 


Record size (in bytes) of maximum record excluding header 


Segment tag for GET/PUT module (S TAG GP MOD) 


Segment tag for record area address (S TAG RA) 


Record area address, first byte of record area 


File identifier for data file (8 bytes EBCDIC) 


a Segment tag for save area address (S TAG SA) 


Save area address, calling program's linkage and register save area 


Error offset, offset (in bytes) to error address from beginning of BDT 


Segment tag for record address pointer (S TAG RAP) 


Record address pointer, first byte address of active record in active |/O data buffer 


Relative record number, record number relative to first record in the file 


Current block number, physical block number present in active buffer 


| 


Logical record number, number of active record in active buffer 


If PU=1, the record address pointer has been updated following a PUT or reset to the first record in the active 
buffer. 


Active buffer (AB) 
0 First buffer 
1 Second buffer 


PUT flag (P). if P=1, record has been written in the active data buffer. 


Unit record flag (UR). If UR=1, device is not disc or tape. 


U 
< 
a 
oO 


114-115*; 


@o]lnr ~ o 
NI 


Table 2-9. Buffer Description Table Format for Sequential Files (Continued) 
Description 
Limits flag (L). tf L=1, limits are defined for relative files 


1/O register flag (1) 
0 Record area 


1 (/O register 


Verify flag (V). If V=1, write verify is performed. 


Skip flag (SK). If SK=1, error option is to skip error. 
Ignore flag (IG). If 1G=1, ignore option was selection. 
Binary bit (B). If B=1, binary cards are to be read. 


1/O usage (USE) 


00 Input 

01 Update 

10 Output 
Work area 


Move routine. Data movement routine consisting of a MOVL instruction followed by a BR instruction. 


Block |/O packet used to issue service requests such as CLOVE, POSITION, and RESET. 


Buffer 1/O packet for 1/O between the data file and the first 1/O buffer. 


Buffer 2 1/O packet for |/O between the data file and the second 1/O buffer. (Optional) 


Segment tag for error address (S TAG EA) 


Error address, address of error return 


| 92-93t 


*Byte positions unique to BDT for sequential files when buffer 2 is present. 
tByte positions unique to BDT for sequential file when buffer 2 is absent. 
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Table 2-10. Buffer Description Table Format for Relative Files 


GET/PUT Address 


Block Size 


0 — ee 
21 ne | FTYP LABL | am | at | Blocking Factor 
4 


10 
12 


44 


46 


56 


66 
68 


Record Size 


S TAG GP MOD | S TAG RA 


Record Area Address 


File Identification 


S TAG SA 


Save Area Address 


E 


Offset 


S TAG RAP 


Record Address Pointer 


Relative Record Number 


Current Block Number 


Logical Record Number 
de 


Work Area 


Move Routine 


Block 1/O Packet 


Buffer 1 I/O Packet 
88 | | 
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Table 2-10. Buffer Description Table Format for Relative Files (Continued) 


epee enreraong 


Buffer 2 1/O Packet 


S TAG AK 


Key Address Pointer 


116 

Limit X 
118 
120 

Limit Y * 
122 
124 

Offset 


126 |. 


S TAG EA 


Error Address 


128 
130 


*Optional 


If buffer 2 is absent, bytes 90 through 109 end the BDT as follows: 


e STAG AK 


Key Address Pointer 


94 
Limit X 
96 
98 
Limit Y : 
100 
102 
Offset 


106 


S TAG EA 


108 Error Address 


*Optional 


2.95 


Byte Bit 


o + : 


> 
o 


vi 


@ 
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Table 2-10. Buffer Description Table Format for Relative Files (Continued) 


Description 


External address of the GET/PUT module processing this file 


Number of buffers (NB) 
(@] One buffer 
1 Two buffers 


File Type (FTYP) 


00 Sequential 
01 Relative 
10 Indexed 


Shared buffer flag (S). If S=1, 1/O buffers are shared with other files. 


Label processing (LABL) 


00 No labels 
01 Nonstandard labels 
10 Standard labels 


Access Methad (AM) 
0 Sequential 


1 Random 


Record type (RT) 
0 Fixed length 
1 Variable length 


en ana ne a rn fh i tenes 


Blocking factor, number of records per block (0-255) 


Block size (in bytes) of the {/O buffers, size must include record headers 


Record size (in bytes) of maximum record excluding header 


Segment tag for GET/PUT module (S TAG GP MOD) 


| 
j 
i 


N 
= 


22,23 


| 


28,29 


Ww 
[é) 


oh 
» 
_ 
© 
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Segment tag for record area address (S TAG RA) 


Record area address, first byte of record area 


File identifier for data file (8 bytes EBCDIC) 


Segment tag for save area address (S TAG SA) 


Save area address, calling programs linkage and register save area 


Error offset, offset (in bytes) to error address from beginning of BDT 


Segment tag for record address pointer (S TAG RAP) 


Record address pointer, first byte address of active record in active !/O data buffer 


Relative record number, record number relative to the first record in the file 


Tabie 2-10. Buffer Description Table Format for Relative Files (Continued) 
Description 


Current block number, physical block number present in active buffer 


Logical record number, number of active record in active buffer 


If PU=1, the record address pointer has been updated following a PUT or reset to the first record in the active 
buffer. 
Active buffer (AB) 

0 First buffer 

1 Second buffer 


PUT flag (P). If P=1, record has been written in the active data buffer. 


Unit record flag (UR). If UR=1, device is not disc or tape. 


Limits flag (L). If L=1, limits are defined for relative files. 


1/O register flag (1) 
0 Record area 


1 {/O register 


Verify flag (V). If V=1, write verify is performed. 


Skip flag (SK). If SK=1, error option is to skip error. 


Ignore flag (IG). If 1G=1, ignore option was selected. 


Binary bit (B). If B=1, binary cards are to be read. 


1/O Usage (USE) 


00 Input 

01 Update 

10 Output 
Work Area 


Move routine. Data movement routine consisting of a MOVL instruction followed by a BR instruction. 


Block |/O packet used to issue service requests such as CLOVE, POSITION, and ADD KEY/DELETE KEYS. 


Buffer 1 1/O packet for 1/O between the data file and the first I/O buffer. 


Buffer 2 1/O packet for |/O between the data file and the second |/O buffer. 


Segment tag for key address pointer (S TAG AK) 


“0 | 

. 
re 

slo 

6,7 

42-45 

46-55 ’ 

56-67 

68-89 -) 

90-111* 

113* ,91T 

a 

92,93T 


Key acldress pointer. First byte address of key address field for relative file. 
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Table 2-10. Buffer Description Table Format for Relative Files (Continued) 


Description 


116-119*: 
94-97 
120-123*; 
98-101 Tt 


Limit X, lower limit for processing. Optional. 


Limit Y, upper limit for processing. Optional. 


124-127*; Offset, lower limits defined when file was first created. Optional. 


102-105t 


129* ;107t 


Segment tag for Error Address (S TAG EA) 


130,131*; Error address. Address of error return. 


108,109t 


“Byte positions unique to BDT for relative files when buffer 2 is present. 
TByte positions unique to BDT for relative files when buffer 2 is absent. 
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Table 2-11. Buffer Description Table Format for indexed Files 


0 
2 | NB FTYP | 5S) 
4 


6 


GET/PUT Address 


LABL Blocking Factor 


Block Size 


Record Size 


8 S TAG GP MOD 


10 


12 


36 
38 


ool ru] aa] e [cor] ws] wl | vi 
42 


44 


46 


56 


66 


1 


S TAG RA 


Record Area Address 


File Identification 


S TAG SA 


Save Area Address 


Error Offset 


S TAG RAP 


Relative Address Pointer 


Relative Record Number 


Current Block Number 1 


Logical Record Number 


Work Area 


Move Routine 


Block t/O Packet 


Buffer 1 1/O Packet ] 
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Table 2-11. Buffer Description Table Format for indexed Files (Continued) 


20 | es | 


Index Buffer 1/O Packet 


110 
112 K3 | S TAG AK 
114] KEYADR1 Address Pointer 
116 C, | Co 
118 Index Buffer Block 
120 bid 
Current Index Black. 
122 
124 Key Size | S TAG IKP 
126 Index Block Key Address Pointer 
128 Directory to the Directory Block Address 
130 Number of Directory Blocks 
132 
Physical Block Number 
134 
136 


Compare Routine 


aris STAG 


KEYADR2 Address Pointer 


Buffer 2 1/O Packet 


Current Block Number 2 


S TAG HLDB 


178 Directory to the Directory Block Pointer 


S TAG EA 


182 Error Address 
*Optional 


If buffer 2 is absent, bytes 150 through 157 end the BDT as shown: 
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*Optional 


Table 2-11. Buffer Description Table Format for Indexed Files (Continued) 


S TAG HLDB 


Directory to the Directory Block Pointer 


S TAG EA 


Error Address 


Description 


External address of the GET/PUT module processing this file 


Number of buffers (NB) 
0 One buffer 


1 Two buffers 


File type (FTYP) 


00 Sequential 
01 Relative 
10 Indexed 


Shared buffer flag (S). If S=1, |/O buffers are shared with other files. 


Label processing (L.ABL) 


00 No labels 
01 Nonstandard labels 


10 Standard labels 


Access method (AM) 
0 Sequential 


1 Random 


Record type (RT) 
0 Fixed tength 
1 Variable length 


Blocking factor, number of records per block (0-255) 


Block size (in bytes) of the I/O buffer(s), size must include record headers 


Record size (in bytes) of maximum record excluding header 


Segment tag for GET/PUT module (S TAG GP MOD) 


Segment tag for record area address (S TAG RA) 


Record area address, first byte of record area 


File identifier for data file and information file (8 bytes, EBCDIC) 
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Table 2-11. Buffer Description Table Format for Indexed File (Continued) 


Descr:ption 


HiEE 


ole hah 
— 
6,7 
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Spread factor (K4), indicating how many passes made on each track 


Segment tag for save area address (S TAG SA) 


Save area address, calling program’s linkage and register save area 


Error offset, offset (in bytes) to error address from beginning of BDT 


Number of blocks per track minus one (K 2) 


Segment tag for record address pointer (S TAG RAP) 


Record address pointer, first byte address of active record in active |/O data buffer 


Relative record number, record number relative to the first record in the file 


Current block number 1, physical block number present in data buffer 1 


(f PU=1, the index block key address pointer was updated by a DELR, PUT, or PUTU instruction in sequential 


access mode, 


Active buffer (AB) 
0 First buffer 
1 Second buffer 


PUT flag (P). If P=1. record has been written in the active data buffer 


End-of-file flag (EOF). If EOQF=1, the end-of-file has been reached. 


Index sharing flag (IS). If 1S=1, index buffer is shared with data buffer. 


Index file flag (IF). If 1F=1, index block was just read or written. 


1/O register flag (I) 
0 Record area 


1 1/O register 


Verify flag (V). If V=1, write verify is performed. 


ignore flag (IG). !f 1G=1, ignore option was selected. 


Previous GET flag (PG). If PG=1, last operation was a GET. 


Index write flag (IW). If IW=1, KEY is added or deleted in current index block. 


1/O usage (USE) 


00 Input 

01 Update 

10 Output 
Work Area 


Move routine. Data movement routine consisting of a MOVL followed by a BR instruction. 


Table 2-11. Buffer Description Table Format for Indexed Files (Continued) 


Bit Description 


Block 1/O packet, used to issue service requests such as CLOVE, POSITION, and ADD KEY/DELETE KEYS. 


Buffer 1 1/O packet for 1/O between the data file and the first |/O buffer. 


Index buffer !/O packet. 1/O parameter packet for t/O between the information file and the index buffer. 


Number of blocks per pass minus one (Ka). 


Segment tag for key address 1 pointer (S TAG AK) 


114,115 


Key address 1 (KEYADR1) pointer, first byte address of key address 1 field 
Current pass boundary counter (C7) 

Current track boundary counter (C9) 

Index buffer size, in bytes 

120-123 


Current index block number; physical block number present in index buffer. 


Key size, size (in bytes) of primary key field 


Segment tag for index block key address pointer (S TAG !KP) 


126,127 Index block key address pointer, first byte address of active key in index buffer 


128,129 


Block address of directory to the directory block 
130,131 Number of directory blocks written 
132-135 Physical block number of data block to be read or written 


Compare routine, data comparison consisting of a CMP X instruction followed by a BR instruction. 


136-145 
146 KEYADR2 flag {F) 


0 KEYADR2 not present 
1 KEY ADR2 present 


Directory to the directory block flag (D) 
0 Directory to the directory block in mass storage 


1 Directory to the directory block in main storage 


Segment tag for key address 2 (KEYADR2) pointer (S TAG FK) 


178,179*; 
162,153t 


Key address 2 (KEYADR2) pointer 
Buffer 2 1/O packet, parameter packet for |/O between data file and second I/O buffer 
Current block number 2, physical block number present in data buffer 2 


Segment tag for directory to the directory block pointer (S TAG HLDB) 


Directory to the directory block pointer, first byte address of main storage directory to the directory block 
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Table 2-11. Buffer Description Table Format for Indexed Files (Continued) 


Description 


181*;155t 
182,183*; 
156,157t 


*Byte positions unique to BDT for indexed files when buffer 2 is present. 
tByte positions unique to BDT for indexed files when buffer 2 is absent. 


Segment tag for Error Address (S TAG EA) 


Error address, address of error return 
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INTRODUCTION 


The block level of input/output processing may be 
applied either to files which were previously 
processed at the logical level” or to files intended for 
use at the block level only. But whatever the 
organization of the file being processed, the data is 
referenced by key block number or as next data 
block for the unit record devices. 


The basic unit of data transfer at the block (and 
physical) level is the block. Thus the 
block-input/output user may only read or write a 
whole block of data at a time (not individual records 
within a block). 


lf the user is operating on files created specifically for 
block input/output use, he is free to establish within 
the blocks any arrangement or grouping of logical 
records he wishes, and the blocking and deblocking of 
these records must of course be performed by the 
user himself. However, it should be noted that if he 
wishes to operate on previously-created files which 
were used for logical input/output, he must be aware 
of the pre-established logical structure of the data 
within the blocks. 


*Sequential and relative files may easily be processed by 
block input/output but it is not practical to apply block 
input/output to indexed files. 


3. BLOCK INPUT/OUTPUT 


GENERAL RULES 


Tape and disc files for block input/output processing 
are created in the same way as those created for 
logical input/output (that is, through Control 
Language //DEF statements external to the program 
or ALLOC macros internally). These are standard 
system file structures and the following rules of file 
logic must be observed when processing them: 


e A file must be opened before it may be 
processed 


e All blocks within a given disc file must be of 
the same length 

e@ Blocks must be at least two bytes long for 
disc requests (printer and card punch 
requests are two bytes long). 


e Block numbers may go from 1 to 232.1 (disc 
block is 224-1) 

e All buffers must begin on word boundaries 
for disc 


e Read buffers will terminate on word 
boundaries for disc 


In addition, the following restrictions should be 
noted: 


e@ Processing across volume boundaries on 
sequential files is not allowed without calling 


CLOVE 

e@ Multi-block reading will only be 
implemented for files with blocks of an even 
byte length 


e Key fields are not supported for disc storage 
and will be ignored if present 
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BLOCK INPUT/OUTPUT CODING 


A set of system macro instructions is provided for 
block input/output coding. The basic macros are 
READ, WRITE, POSITN and CNTRL. With these 
instructions blocks of data may be read and written, 
files may be positioned to particular blocks in 
preparation for processing, and certain hardware 
commands not involving data transfer may be 
performed. Other facilities that might be required are 
provided by the STATUS macro, which allows file 
status checking; the TYPE macro, which returns 
device type; and the RESET macro, which enables 
error conditions to be cleared (to allow for 
continuation after an error). 


A particular block of data within a file is referred to 
by number. All files are ordered sequentially, with 
the first block of the file being block number 1. As an 
aid to processing files in a sequential manner, explicit 
block numbers are not necessary. Any data request 
with an implied block number causes the block 
number to be updated. The block referred to by a 
request is determined relative to an internal block 
number maintained by the I/O control routines. 


BLOCK READING 


The READ macro reads a block of data from a 
specified file and stores it at a specified buffer 
address. The number of the block to be read is 
obtained either directly from the READ call (if 
specified) or by adding 1 to the current block count 
saved by the system. After the READ is executed the 
updated block number will replace the old block 
number in the file’s block counter so that a 
subsequent READ will automatically read the next 
block. 


lf a POSITN macro (to the same file) is executed 
immediately preceding a READ, the current block 
number will be used without change. When a file is 
openec for input (reading) its block counter is 
initially set at 1. 


BLOCK WRITING 


The WRITE macro transfers a block of data from a 
specified buffer address to a specified file. The 
number of the block into which the data is to be 
written is obtained either directly from the WRITE 
call (if specified) or by adding 1 to the current block 


Table 3-1. Assumed Block Numbers 


Operational Sequence 


All: 


Disc: 


All: 


POSITN POSITN 


READ WRITE 


Mag Tape: 


Disc: 


Mag Tape: 
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Effect 


Reader/Punch: 


Reader/Punch: 


Each Read causes a one-count increase in the block number 


before the operation. 

Records are read sequentially. 

Each Write causes.a one-count increase in the block number 
after the operation. 


Records are written sequentially. 


The block referred to by Positn is used for the Read or Write request. 


The block written replaces the block just read. 


The block is written into the card just read (file open for update); 
and the block is written into the next card (file open for output). 


The block is written after the block just read. 


The block number is increased after the WRITE operation and 
not prior to the Read operation. This avoids skipping the next 
sequential block. 


Card n is written. Card n+1 is then read. 


Invalid sequence. 


count saved by the system. After the WRITE is 
executed the updated block number will replace the 
old block number in the file’s block counter so that a 
subsequent WRITE will automatically write into the 
next block. 


If a POSITN macro (to the same file) is executed 
immediately preceding the WRITE the current block 
number will be used without change. 


lf a READ macro immediately precedes a WRITE, 
the current block number will be increased by 1 in 
the normal way for a magnetic tape file but will not 
be altered in the case of a disc file. 


When a file is opened for output (writing), what 
happens to the block counter depends on the type of 
file. For scratch, temporary and work files, opening 
the file sets the block counter to 1. For permanent 
files, however, the block counter will not be altered 
and will retain the value left in it on the previous use. 
This enables data already contained on the file to be 
saved between different job runs by adding new data 
only to the end of the file (unless otherwise 
specified). 


Table 3-1 gives the assumed block numbers for the 
READ, WRITE, and POSITN macros. 


BLOCK POSITIONING 


The current block number of a file may be preset by 
a POSITN macro for subsequent reading or writing. 
This macro sets the current block counter of a 
specified file to a specified value. 


DEVICE CONTROL COMMANDS 


input/output device control commands, not involving 
a data transfer, may be implemented by the CNTRL 
macro. This macro transmits a specified command to 
the device containing a specified file. Typical 
commands transmitted by this macro are Skip to Top 
of Form for line printer, Rewind Tape for tape drive. 


SPACE MANAGEMENT AND FILE CONTROL 


Space management and file control for block 
input/output are handled by Data Management 
functions described in Section 2. For space 
management ALLOC, EXPAND and PURGE are 
used. For file control OPEN, CLOSE and CLOVE are 
used. 


PROCESSING CONSIDERATIONS 


REQUEST OVERLAP 


Multiple requests to the same file or the same device 
can be issued. However, to avoid ambiguous results, 
separate request blocks and data buffers must be 
used. Requests will be honored in the order of receipt 
within a file. Issuing multiple requests, with the aid of 
the RETURN=YES operand in the requesting macros, 
improves throughput by enabling the system to 
overlap input/output set-up time with data 
transmission. 


PRIORITY 


Input/output requests are processed by the system 
according to the priority of the program which issues 
them. This priority is specified in the Control 
Language //JOB card and is set at the time the job is 
initiated. 


END CONDITIONS 


End conditions are special boundary conditions 
resulting in return indications to the user but not 
considered as errors. 


e End of File (EOF) 


EOF is a logical boundary defined for input 
files. Each device” capable of reading has a 
defined end of file condition. EOF provides 
a condition in the data stream which is 
uniquely detectable by the system. After 
EOF has been detected on disc, magnetic 
tape, or the card reader, a RESET macro 
must be issued before processing may 
continue. 


On the card readert, a data record beginning 
with the characters /* is defined to be an 
end-of-file condition. When EOF is detected, 
the entire record will be transferred to the 
user’s buffer. 


On magnetic tape the EOF condition is set 
whenever a tapemark is detected. 


* An exception to this is the card reader where the /* card is 
used to indicate the EOR condition in the EBCDIC mode. 
In the EBCDIC=NO mode, there is no EOF condition 
detectable by an I/O driver because all data images are 
considered to be legal data. 


tThe operator-selected EOF option on IBM card readers is 
not supported. 


With disc, the EOF condition is set when a 
block with a data-length specification of 
zero has been read. Note that an embedded 
EOF will not be detected, however, during a 
multi-block read. 


e End of Allocation (EQOA) 


EOA is a physical boundary applying only to 
disc output files. An EQOA indication is 
returned any time a block is written into the 
last allocated space for the file. 


e End of Tape (EOT) 


EOT is a physical boundary applying only to 
magnetic tape output files. It signifies that 
the end-of-tape reflective marker has been 
sensed. 


PROCESSING MULTI-VOLUME FILES 


When processing sequential files occupying more than 
one physical volume (disc and tape only), the block 
input/output user must perform volume switching to 
move from one volume to another. 


At any given time, the File Description Table for a 
sequential file” may only describe a single physical 
volume, which limits the current range of processing 
to the described volume. When, during processing, the 
user encounters an EQOV indication or wishes to 
prematurely close the volume and switch to the next 
volume he must issue a CLOVE (close volume) macro 
to continue processing on the next consecutive 
volume. CLOVE ensures that the next volume is 
mounted, by issuing an Operator message if necessary, 
and then modifies the FDT to describe the next 
volume. 


lf there are no more volumes to be processed, the 
EOF/EOA bit (bit 2 of the return information) in the 
CLOVE packet is set. The user is responsible for 
testing this condition. 


SENSE INFORMATION 


The number of bytes of sense information varies with 
the device. All the bytes for the device are maintained 
in the File Description Table, and are updated 
whenever an abnormal completion occurs for reasons 


*An FDT for a relative file describes the whole file, therefore 
eliminating the need for CLOVE in this case. 
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other than logical errors. A STATUS macro request 
transfers this information from the File Description 
Table to the user buffer (to the extent that user 
buffer allows). 


REQUEST TERMINATION 


The user requesting a block I/O operation has two 
options while a request is processed: 


e to wait for the request to be completed. 


e to return to do parallel processing after the 
request is recognized and before the request 
is processed to completion. 


If the user elects to wait for the request to be 
completed before continuing with processing, his 
program will be suspended by the operating system 
until the request has been terminated. 


If the user has returned to do parallel processing, the 
COMPLETE indicator in the parameter string is set 
when the request is returned from the !/O control 
routines. 


ERROR PROCESSING 


At the block input/output level, the system 
automatically provides attempted recovery from 
hardware device errors. If peripheral device error 
recovery is successful, control is returned to the user 
with no error indication. 


In the case of an error return (where peripheral device 
error recovery has been unable to correct the error), 
the program (and the rest of the job) normally is 
aborted. However, if ERRCOMP=YES is coded in the 
request macro, control is returned to the user 
together with return information (Appendix C) thus 
enabling him to process the error condition himself. 
It should be noted that before issuing another request 
to the same file following an error return, the user 
may first have to reset the error condition with a 
RESET macro (Appendix C). 


Examples of block input/output are shown in Figures 
3-1 and 3-2. 


LABEL OPER’N OPERANDS COMMENTS 
OPEN IDENT=CARDIN,IOTY P=B,USAGE=I OPEN CARD INPUT FILE 
OPEN IDENT=PRINT,IOTYP=B,USAGE=0 OPEN PRINTER OUTPUT FILE 
START READ IDENT=CARDIN,DATABUF=CRDIMG READ A CARD 
TBIT _ 2START+4 CHECK FOR END-OF-FILE IN REQ BLOCK 
BOV END IF EOF, GO CLOSE FILES AND END PROGRAM 
WRITE IDENT=PRINT, DATABUF=CRDBUF PRINT CONTENT OF ACARD 
B START GO READ ANOTHER CARD 
END CLOSE IDENT=CARDIN,IOTYP=B CLOSE CARD FILE 
CLOSE IDENT=PRINT,IOTYP=B CLOSE PRINTER FILE 
HALT TERMINATE PROGRAM 


“eee HE HK RH HH e HK * * DNATA AREA * * * * FP * # # H HH HH HR H HH HH RH & 


CROBUF WwRs 80 CARD/PRINT BUFFER 
CARDIN wDD C’CARDIN ’ CARD FILE IDENT 
PRINT woop C’PRINT ’ PRINTER FILE IDENT 


Figure 3-1. Block 1/O Program to Read Cards and Print 


START 


OPEN 
FILES (DISC FILE 
OPENED FOR OUTPUT} 


RESET 
DISC BUFFER 
INDEX 


MOVE CARD 
IMAGE TO 
DISC BUFFER 
(INDEXED) 


INCREASE COUNT, 
DISC BUFFER 
INDEX 


YES 


WRITE 
BUFFER 


TO DISC 
(ONE BLOCK) 


CLOSE DISC FILE 
& REOPEN IT 


FOR INPUT 


READ A BLOCK 
FROM DISC 


YES 


RESET 


DISC BUFFER 
INDEX 


YES 


MOVE ONE 
CARD IMAGE 
FROM DISC BUFFER 


TO PRINT LINE 
(INDEXED) 


PRINT 
CARD IMAGE 


INCREASE COUNT, 


DISC BUFFER 
INDEX 


DISC 
BUFFER 
EMPTY 


Figure 3-2. Block {/O Program to Read Cards into Disc File 


CLOSE 
FILES 


DISCWR 
RESET 


DISCRD 


PRINT 


END 


* &* & K&L 


CBUF 
DBUF 
PBUF 
CFIL 
PFIL 
DFIL 


_ IDENT=PFIL,BUFADR=PBUF 


* * * * * * DATA AREA * * * * * * 


OPERANDS COMMENTS 


IDENT=CFIL,IOTYP=B,USAGE=I 
IDENT=DFIL,IJOTYP=B,USAGE=0 
IDENT=PFIL,IOTYP=B,USAGE=0 
3,0 

IDENT=CFIL,BUFADR=CBUF 
DBUF (80, 3),CBUF (80) 


OPEN CARD FILE 

OPEN DISC FILE FOR OUTPUT 

OPEN PRINTER FILE 

ZERO DISC BUFFER INDEX 

READ A CARD 

MOVE CARD IMAGE TO DISC BUFFER 


2,CARDRD+4 CHECK FOR END-OF-FILE 

RESET iF EOF, GO READ DISC FILE 

3,80 INCREMENT BUFFER INDEX 

3,800 CHECK IF BUFFER FULL 

CARDRD IF NOT, GO READ ANOTHER CARD 


IDENT=DFIL,BUFADR=DBUF,RETURN=YES 
START 

IDENT=DFIL,IOTYP=B 
IDENT=DFIL,IOTYP=B,USAGE=I 
IDENT=DFIL,BUFADR=DBUF 


WRITE 10-CARD BUFFER ON DISC FILE 
GO READ ANOTHER 10 CARDS 

CLOSE DISC FILE 

REOPEN DISC FILE FOR INPUT 

READ A BLOCK FROM DISC 


2,DISCRD+4 CHECK FOR END-OF-FILE 
END IF EOF, GO END PROGRAM 
3,0 ZERO DISC BUFFER INDEX 


MOVE CARD IMAGE FROM DISC BUFFER TO PRINT 
LINE 
PRINT A CARD IMAGE 


PBUF(80),DBUF(80, 3) 


3,80 INCREMENT DISC BUFFER INDEX 

3,800 CHECK IF BUFFER HAS BEEN EMPTIED 
PRINT IF NOT, GO PRINT ANOTHER CARD IMAGE 
DISCRD GO READ ANOTHER BLOCK FROM DISC FILE 


IDENT=CFIL,IOTYP=B 
IDENT=DFIL,IOTYP=B 
IDENT=PFIL ,IOTYP=B 


CLOSE CARD FILE 
CLOSE DISC FILE 
CLOSE PRINTER FILE 
TERMINATE PROGRAM 
* 


80 CARD BUFFER 


800 DISC BUFFER 

80 PRINT LINE 

C'CFIL ; CARD FILE IDENT 

C’PFIL . PRINTER FILE IDENT 
DISC FILE IDENT 


C'DFIL ' 


Figure 3-2. Block 1/O Program to Read Cards into Disc File (Continued) 


3-7 


4. PHYSICAL INPUT/OUTPUT 


INTRODUCTION 


The physical 1/O interface gives the user ability to 
utilize the device drivers to perform 
hardware-dependent !/O operations. 


Physical input/output is independent of the system’s 
file processing scheme. Whereas block input/output 
deals with files, physical input/output deals directly 
with hardware devices. Use of physical !/O assumes 
the following: 


@ Devices to be used must be defined by 
Control Language //DEF statements 


e Devices must be opened for data 
transmission (by the OPEN macro) 


e Error recovery will automatically be 
provided by the system (but may be 
bypassed if desired) 


PHYSICAL INPUT/OUTPUT CODING 


DEFINING AND OPENING DEVICES 


Each device to be used for a physical input/output 
operation must first be assigned by the system. This is 
done through a System Control Language //DEF 
statement. An OPEN macro must also be coded in the 
‘user program to return the assigned unit ordinal used 
in building the PCB (next paragraph). 


PERFORMING THE PHYSICAL 1/O OPERATION 
To perform a physical !/O operation, three entities 
must be created in the user’s program: 

@ acommand program 

@ a physical command block (PCB) 

e ado I/O” instruction (EXCP) 
The command program does not consist of directly 
executable codes but is a chain of ‘“’command words” 
which will be operated on by the system’s 1/O 
processing routines. The program should be located in 


a data area of the program and may be built by means 
of COMMAND macros. 


Examples of command word functions are these: 


@ print a record on a line printer 
e select a stacker on a card reader 
e seek on a disc file 


@ read a card record from a card reader 


For every physical input/output operation a Physical 
Control Block (PCB) is required. The PCB should be 
located in a data area. The Physical Control Block 
may be build by a PCB macro. 


To initiate the execution of physical 1/O command 
programs a single action macro, EXCP, is required; it 
must be coded in line with the program's executable 
code. While the above general requirements are fixed, 
there are several variations in the detailed 
implementation, some of which allow more efficient 
use of memory space than others. Efficient use of 
device may be another consideration for not doing 
this. First the basic method will be explained, and 
then the more efficient methods will be described. 


Basic Method 


In the simplest situation, there is one PCB for each 
command program and one EXCP for each PCB 
(Figure 4-1). In this case, the address of the command 
program may be assembled into the PCB by the 
CPADR operand in the PCB macro, and the address 
of the PCB may be assembled (by means of the PCB 
operand) into the corresponding EXCP macro. 


Sharing a PCB 


When there are several command programs applying 
to the same device, coding efficiency may be 
improved by having these command programs all 
share the same PCB (Figure 4-2). In this case the 
address of the appropriate command program must 
be dynamically supplied to the PCB before each 
operation. This may be done by supplying the 
appropriate command program address through the 
related EXCP (by means of the CP operand) rather 
than by presetting it into the PCB. Thus a group of 
EXCP’s may all specify the same PCB but different 
command programs. Input/output operations to 
different devices may be overlapped by coding 
RETURN=YES in the appropriate EXCP instruction. 
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Figure 4-1. Basic Method for Physical 1/0 


Figure 4-2. Sharing a PCB 


Figure 4-3. Sharing an EXCP 


Sharing an EXCP 


Sometimes it is possible to employ a single EXCP to 
operate through a PCB on several command programs 
or even to operate on several PCB’s (Figure 4-3). 
When this is to be done, the user may set up a table 
of command program addresses (and PCB addresses, 
if there are multiple PCB’s). The EXCP will then refer 
to the address tables at execution time by indirect 
addressing with the CPADR operand and PCBADR 
Operand. 


OVERLAPPED OPERATION* 


There is a PCB for each input/output device; 


input/output operations to different devices may be 


overlapped by coding RETURN=YES in the relevant 
EXCP instruction(s). This causes control to be 
retained by the requesting program (while the 1/O 
operation itself is concurrently being processed by 
the system), thus enabling initiation of another I/O 
operation before the first has been completed. 


Beyond this, it is also possible to overlap requests to 
the same device, but it should be remembered that a 
separate PCB and data buffer will be required for 
each such overlapped request. When multiple requests 
are issued in this manner, throughput will be 
improved since the system is able to overlap I/O 
set-up time with data transmission. (The system will 
always service multiple requests to the same device in 
order of receipt.) . 


PHYSICAL REQUEST TERMINATION 


When a physical 1/O request is completed, several 
values are returned to the calling program in the 


* The effectiveness of overlapped coding is dependent on 
the number of Queue Entry Blocks available in the 
system, a SYSGEN variable. 


command block (PCB): 


e address of the last command word executed 
or attempted to be executed 


e hardware status indication 


@ residual byte count of last data operation 


PHYSICAL t/O RESTRICTIONS 
@ Byte count must be less than 216-1 (65K) 


e Multi-record read operations must not 
attempt access to records across track 
boundaries (disc). 


e The user is responsible for validating a ‘‘read 
count field’’ request (disc). 


ERROR PROCESSING 


System error recovery (Appendix C) is provided by 
default just as it is at the block level. However, at the 
physical level, system error recovery may be bypassed 
by coding ERROPT=NO in the PCB macro. In any 
case, an uncorrected error will always cause the 
program to be aborted unless the operand 
ERRCOMP=YES is coded in the EXCP macro making 
the request. When ERRCOMP=YES is used, control is 
returned to the user in the event of an error, together 
with return information in the PCB so the user may 
either ignore it or process the error himself. 


EXAMPLE OF PHYSICAL 1/0 PROGRAM 


Figure 4-4 shows a block diagram of a program to 
read cards and print. A coding form illustrates the 
code necessary for this physical |/O program. 
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CLOSE 
FILES 


PRINT 
EBCDIC 
CONTENT 


OF CARD 


Figure 4-4. Physical 1/O Program to Read Cards and Print 
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5, CONTROL PROGRAM SERVICES 


INTRODUCTION 


The executive services are those implemented directly 
by the Control Program itself to assist the user in 
various areas, such as input/output request control 
and communication between job steps. 


SERVICE REQUEST CONTROL 


Control over the issuance of service requests by the 
user program may be aided by the WAIT, INFORM 
and DELAY™ macros. In one way or another, all of 
these macros can detect completion of the user’s 
service requests. 


WAIT simply suspends program execution until 
completion of the specified request or requests. 


WAIT is used to wait for any one or all of the 


outstanding service requests. 


DELAY enables the user to suspend execution for a 
specific period of time with the option of breaking 
the delay (resuming execution) on the completion of 
any service request. 


INFORM offers the capability of detecting the 
completion of a service request in the interval 
between the issuances of the INFORM and its actual 
processing by the system. This capability, which is 
not available with the WAIT macros, is implemented 
with the aid of a user-supplied count of the number 
of outstanding requests he has at the time of issuing 
the INFORM. By comparing this count with its own 
count of outstanding requests, the system can 
determine whether any requests had been completed 
in the time since INFORM was issued by the user. In 
addition to this, INFORM always returns control 
immediately to the user (it has an implied 
RETURN=YES operand) so that he may continue 
processing and subsequently check completion of the 
INFORM by testing the complete bit in the request 
block. 


INTER STEP AND CONTROL LANGUAGE 
COMMUNICATION 


User programs running as separate job steps in a 


multi-step job have two ways of transferring data to 
one another: The POST/RPOST pair of macrost and 
the SETCOM/GETCOM pair of macros. 


In addition, any program may influence the 
subsequent course of the job by means of the SETIF 
macro which posts information to be tested by an 
//\F statement between later job steps. 


The POST/RPOST pair of macros post and read a 
single byte of data in the Job Control Table, whereas 
the SETCOM/GETCOM pair post and read a full eight 
bytes. 


FINDING PARTITION SIZE 


When a program is being written which is expected to 
run in partitions of various sizes, it would often be 
advantageous to code the program in such a way as to 
occupy as much of the partition as is currently 
available. 


To achieve this flexibility, a dynamic determination 
of current partition size is necessary; this is provided 
by the MEMLIM macro. 


MEMLIM informs the program of the size of the user 
portion of the partition in which it is currently 
running by returning the starting address of the last . 
addressable 256-byte page, expressed as an absolute 
address. In effect, MEMLIM returns the starting 
address of the last usable page below the partition 
space pool. For this reason, programs which make use 
of MEMLIM should always specify a fixed-length 
space pool through the appropriate Link Editor 
directive, since otherwise the space pool will 
automatically commence on the page boundary 
following the space allocated to the program. 


*DELAY is not available on the minimal system. 


tPOST/RPOST conform to the IBM UPSI bit scheme. 
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READING DATA FROM //PAR CARDS 


Data may be read from //PAR cards supplied in the 
job control deck by means of the ACCEPT macro. 
This macro transfers the contents of a single //PAR 
card into a specified buffer. On the first execution of 
ACCEPT, the first //PAR card is read; successive 
executions automatically read the rest of the //PAR 
cards consecutively. After the last //PAR card has 
been read the next execution of an ACCEPT transfers 
program control to a specified ‘‘end’’ address. 


The user may also specify a particular //PAR card by 
using the PARNUM keyword in the ACCEPT macro. 
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WRITING TO THE SYSOUT FILE 


SYSOUT files are system output files, one of which is 
created uniquely for each job*. Any user program 
may write a one-line EBCDIC message on the 
SYSOUT file for the job by means of the DISPL AY 
macro. The location of the message buffer should be 
specified on the related DISPLAY macro call. 
DISPLAY expands to in-line processing code, 
including an embedded block I/O WRITE to the 
SYSOUT file. 


*The Control! Language Services Reference manuals contain 
further explanations. 


6. INTERACTION OF DATA MANAGEMENT 
AND THE CONTROL LANGUAGE 


Through the //DEFINE statement, a run-time 
interaction between certain Data Management 
services and Control Language services is provided. 
This interaction gives the program independence from 
reassembling to make changes that can then be made 
at run-time through the control language statements. 


Both the logical !/O level (described in Control 
Program and Data Management Services, Basic 
Reference) and the block I/O level require space 
management. Users of the physical 1/O level require 
no space management. The Control Language and/or 
the space management macros (ALLOC, EXPND, and 
PURGE) can allocate, expand, or purge files. 


lf the Control Language is externally allocating a file, 
the parameters are passecl to the ALLOC packet by. 
the Step Initiator. A file is allocated by either the 
ALLOC macro or by the //DEFINE statement, not 
both. The ALL OC macro uses the FILENAME, MSC, 
and VOLUME parameters specified in the //DEFINE 
statement to override the parameter packet at 
execution time. . 


A space management routine is called in response to a 
service request from either the Control Language 
processor or the user program. The Control Language 
request for Allocate or Expand may be generated at 
step initiation time using parameters given in the 
//DEFINE statement. The Control Language request 
for Purge may be generated at step termination time, 
using parameters given in the pertinent files disc 
catalog entry. The user program request for Allocate, 
Expand, or Purge is generated at assembly time, using 
parameters given as keyword in a macro call. The user 
request may optionally make reference to 
FILENAME, MSC, and VOLUME information given 
in a //DEFINE statement. If so, at execution time, 
the FILENAME and MSC parameters in the 
//DEFINE statement override the equivalent 
parameters contained in the user request. 

Table 6-1 summarizes the use of different Control 
Language parameters as used by the Step Initiator, 
OPEN, CLOVE, ALLOC, EXPND, and PURGE. 
Further explanations of the Control Language can be 
found in Control Language Services, Extended 
Reference. 
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Control Language 
Keyword Parameter 


IDENTIFIER 


FILENAME 


STATUS 


DEVICE 


VOLUME 
(and |\VOLUME 
for OPEN) 


SPREAD 


CONTIGUOUS 


NUMBER 


Table 6-1. Summary of Data Management and Control Language Interaction 


Control Language 
Step Initiator 


Not used 


Used to search 
central catalog to 
determine volumes 
of a cataloged file. 


File usage checked 


for partition conflicts. 


File type passed to 
ALLOCATE packet* 
if NUMBER is 
specified. 


Not used by Step 
Initiator 


Used to allocate 
peripheral re- 
sources to files. 


Used to mount 
Packs or tape reels 
when possible and 
verify the mount 
by comparison of 


~Ivolume with volume 


identifier in the 
volume label. 


Passed to the 


ALLOCATE packet* 


Passed to the 


ALLOCATE packet* 


Not used by Step 
Initiator 


Used to compute 
block size from 


SIZE and BLOCK 


for ALLOCATE 
when NUMBER is 


specified. 


Used to compute 
number of blocks 
from BLOCK and 
NUMBER for 
ALLOCATE 
Aliso indicates 
need of ALLOC. 


i 
i 
4 


OPEN Macro 


Must match file 
identifier in 
OPEN macro. 


Override DEFLB 
information. 


Not used by OPEN 


Override DEFLB 
information. 


Not used by OPEN 


When volumes have 
been mounted by 
Step Initiator, they 


: are verified by 


comparison with 
unit table volume 
identifier entries. 


; When not mounted, 
| OPEN mounts the 

' volume(s) and 

| verifies against 

} volume label. 


Not used by OPEN 


Not used by OPEN 


Indicates type of 
label processing 
for the job. Con- 


| trol Language 


overrides program 
specification, 


Not used by OPEN 


Not used by OPEN 


CLOVE Macro 


Must match file 
identifier in 
CLOVE macro. 


Override DEFLB 
information. 


Not used by CLOVE 


Override DEFLB 
information. 


Not used by CLOVE 


Used to mount and 
verify successive 
volumes of se- 
quential files. 


Not used by CLOVE 


Not used by CLOVE 


Indicates type of 
label processing 
for the job. Con- 
trol Language 
overrides program 
specification. 


Not used by CLOVE 


Not used by CLOVE 


ALLOC,.EXPND, 
PURGE Macros 


Must match file identifier 
in macro. 


Override DEFLB informa- 
tion. 


Not used by ALLOC, 
EXPND, or PURGE 


Override DEFLB informa- 
tion. 


Not used by ALLOC, 
EXPND, or PURGE 


Voiume identifiers specify 
which packs are to be 
used for allocation or 
expansion. If omitted, 
shared resources are 
used. PURGE uses 
volume identifiers for 
purging uncataloged files. 


Not used by ALLOC, 
EXPND, or PURGE 


Not used by ALLOC, 
EXPND, or PURGE 


Not used by ALLOC, 
EXPND, or PURGE. 


Not used by ALLOC, 
EXPND, or PURGE 


Not used by ALLOC, 
EXPND, or PURGE 


“Parameters are passed to the ALLOCATE parameter packet by the Step Initiator; the Control Langu’ ge is allocating 


the file. 


Table 6-1. Summary of Data Management and Contro! Language Interaction (Continued) 


Control! Language 
Keyword Parameter 


LOCATION 


ORGANIZA- 


TION 


RETENTION 


CATALOG 


VERIFY 


EXPAND 


Control! Language 
Step Initiator 


Used to compute 
block size. Key 
size portion is 
passed to the 
ALLOCATE 
packet* for 
indexed files. 


Used to compute 
block size for data 
and index files. 


Passed to the 
ALLOCATE 
packet* when 
NUMBER is 
specified. 


Passed to the 
ALLOCATE 
packet* 


Not used by Step 
Initiator 


Passed to the 
ALLOCATE 
packet* 


Passed.to the 
ALLOCATE 
packet* 


Passed to the 
EXPAND packet 


OPEN Macro 


Not used by OPEN 


For tape files, 
Control Language 
supplies block size. 
Default value is 
251 bytes. 


Not used by OPEN 


Not used by OPEN 


Used to generate 


an expiration date 


for tape files. 


Not used by OPEN 


If the file was 
cataloged with 
VERIFY=YES, 
OPEN does not 
interpret the param- 
eter. If not, then 
VERIFY=YES at 
OPEN time will 
temporarily over- 
ride the catalog 
attribute. 


Not used by OPEN 


CLOVE Macro 


Not used by CLOVE 


Not used by CLOVE 


Not used by CLOVE 


Not used by CLOVE 


Used to generate 
an expiration date 
for tape files. 


Not used by CLOVE 


Not used by CLOVE 


Not used by CLOVE 


ALLOC, EXPND, 
PURGE Macros 


Not used by ALLOC, 
EXPND, or PURGE 


Not used by ALLOC, 
EXPND, or PURGE 


Not used by ALLOC, 
EXPND, or PURGE 


Not used by ALLOC, 


EXPND, or PURGE 


Not used by ALLOC, 
EXPND, or PURGE 


Not used by ALLOC, 
EXPND, or PURGE 


Not used by ALLOC, 


EXPND, or PURGE 


Not used by ALLOC, 


EXPND, or PURGE 


*Parameters are passed to the ALLOCATE parameter packet by the Step Initiator; the Control Language is allocating the file. 
**Parameter is passed to the EXPAND parameter packet by the Step Initiator; the Control Language is expanding the file. 
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This section gives the specifications for the block and 
physical I/O level functions of Data Management, 
Block I/O action, Physical 1/O action, and Control 
Program Services. In general, all the macros have the 
following format: 


Name Operation Operand’ 


The name field is an optional field which contains a 
1- to 8-character alphanumeric file address. The first 
six characters must be unique to accommodate the 
standard suffixes used by the system. These are 
discussed in Appendix B of this manual. The names 
ident, labadr, and tag are used as identifiers for the 
software function specified in the operation field of 
the macro prototype. 


The operand field contains keyword parameters 
which may be in any order separated by commas. 
Optional parameters are denoted by brackets, [ ]. 
Parameters with a choice of specifications are 
denoted by braces, { be and the default value is 
underlined. 


Fields are free-form and are separated by blanks; 
thus, no imbedded blanks are allowed within the 
parameter string. If more than one card is necessary, a 
semicolon must appear after the last parameter on 
~ each card except the last. 


Symbolic address (as used in macro prototypes) is the 
1- to 8-character symbol used to identify a coding 
statement. The IDENT parameter is the symbolic 
address of the 8-byte field containing the file 
identifier (left-justified, blank filled). If the pertinent 
file is defined in the Control Language, the file 
identifier referenced by IDENT must be identical to 
the IDENT specified by the //DEFINE statement. 
Unless otherwise stated numbers are assumed to be in 
decimal with no leading zeros. 


DATA MANAGEMENT 


In this section only the block and physical I/O level 
of Data Management macros are given. This level of 
macros include these: 


7. MACROS 


Block 1/O Level Declarative Macro 
DEFLB 


Space Management Macros 
ALLOC 
EXPND 
PURGE 


File Control Macros 
OPEN 
CLOSE 
CLOVE 


1/O Service Macro 
LABRTN 


Block 1/O Macros 
READ 
WRITE 
POSITN 
CNTRL 
STATUS 
TYPE 
RESET 


Physical 1/O Macros 
EXCP 
PCB 


Control Program Macros 
WAIT 
DELAY 
INFORM 
POST- 
RPOST 
SETCOM 
GETCOM 
ACCEPT 
DISPLAY 
MEMLIM 


e Console Communication Macros 


CONSOLE 
MESSAGE 


Appendix B details the service request mechanism 
and details the expansion of these macros. 


BLOCK I/O LEVEL DECLARATIVE MACRO 


A block 1/O level declarative macro, DEFLB, defines 
the file label for Data Management. 


DEFLB — Define File Label 


The DEFLB macro generates file label data into a 
main-memory buffer for creating and checking disc 
file names. The Control Language may also be used to 
create and check file names. The block I/O level space 
management and file control macros use DEFLB. The 
format is as follows: 


Name Operation Operand 


labadr DEFLB FILENAM=name 


[MSC=code] 


FILENAM=name 


Specifies a 1- to 17-character alphanumeric file name. 
The first character may be A-Z, 0-9, or $; A-Z, 0-9, 
and dash are allowed as succeeding characters. Index 
file names are created internally by adding an asterisk 
at the end of the associated data file name. 


MSC=code (Optional) 
Designates a 4-byte EBCDIC modification security 
code, which is used for work and permanent files. If 
omitted, blanks are assumed. 


BLOCK 1/O LEVEL AND PHYSICAL I/O LEVEL 
EXECUTIVE REQUESTS 


The executive request macros generate requests for 
space management, file control, file processing, and 
file positioning at the block 1/O level. These requests 
specify a file identifier and a specific block of data 
within the file. The file control and file processing 
macros are also available at the physical |/O level, 
specifying a unit identifier rather than a file 
identifier. 


Files which are open for block I/O level file 
processing requests are described by a File 
Description Table (FDT) created by OPEN. FDT 
contains a physical description of the file, a 1- to 
8-character file identifier, and current processing 
information about the file (for example, current 
block number and status of last request). File 
processing and positioning requests are made by file 
identifiers and controlled by the FDT. 


Units which are open for physical 1/O level processing 


are assigned by the Control Language. The identifier 
field in OPEN is used to find the correct Control 
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Language entry which gives the unit assignment. The 
//DEFINE statement indicates physical 1/O by stating 
P/O in the file name field. Physical |/O requests are 
made by a unit ordinal which has been returned to 
the user after an OPEN. 


Space Management Macros 


The ALLOC, EXPND, and PURGE macros manage 
space for all disc files. Usually these three functions 
are generated through the Control Language and by a 
space management utility program, which allows 
changes without recompilation of the program; 
however, a user program can directly manage file 
space. 


The allocation of paired files must be done through a 
utility if not done directly from a user program. The 
utility programs may also purge permanent and work 
files if not done directly from the user program. 


Space rnanagement is required for usage of block 1/O 
level and logical 1/O level interfaces. Users of physical 
1/0 level require no space management. 


Space is allocated in increments of tracks. Paired file 
allocation of two files provides minimum arm 
movement for file processing. A contiguous or 
non-contiguous segment of space is allocated to.both 
files starting at the chosen segment. Alternate tracks 
from this space are then assigned to each of the two 
files. File space allocated will be contiguous unless 
contiguous space is unavailable, in which case up to 
12 segments will be allocated. Other allocation 
options are as follows: 


e Multipack files (up to seven packs) 

e Suppression of automatic segmentation 

e Cylinder number specification 
Each clisc pack contains a volume label which is 
created at disc initialization time. A MRX/OS utility 


prograrn may change the volume label and its 
parameters. 


In its device label each disc pack contains pack status 
indication of one of the following conditions. 


Pack Status Meaning 


Any allocation request may 
obtain space from this pack. 


Nonrestricted 


Restricted Only allocation requests with 
packs specified by the Con- 
trol Language may obtain 
space from this pack. 

Locked No further allocation is 


allowed on this pack. 


Some disc drives are classified as shared resource 
drives at initial program load time. The operator 
mounts a set of packs on these drives, which will be 
available for any allocation requests. The remaining 
disc drives (non-shared-resource drives) are each 
assigned by job control to a specific user partition for 
the job step requesting the drives, and may be used 
only by allocation requests associated with the job 
step in the partition to which they were assigned. 


ALLOC — Allocate Space 


The ALLOC macro allocates space for user data files 
and system data files. When volume identifiers have 
not been specified through job control, space will be 
allocated on nonrestricted packs mounted on shared 
resource drives. When volume identifiers have been 
specified through job control, the disc drives on 
which they are mounted will have been assigned by 
job control to the partition (or system function) of 
the program calling ALLOC. Duplicate file names are 
not allowed on the disc catalogs. The format is as 
follows: 


Name Operation Operand 


[tag] ALLOC BLKSIZ=n 
[caracoc- {ts ] 


[con= tio. | 
[csp- {ves }| 


YES 
[paracy L= {wo NO }] 


[eRRcomp- ie ] 


[FILEORG=code] _ 
FILESIZ=n 
[FILETYP=code] 
(t{DENT=symbolic address] 


eal 


INDSIZ=n* 

KEYSIZ=n* 

LABDEF 1=symbolic address 
[LABDEF2=symbolic address] 


RECSIZ=n 


[ReTURN- fio tf 


[SPREAD=n]* _ 


[ venir (no. '] 


*For indexed files only. 


BLKSIZ=n 


Designates the number of 8-bit bytes per block for 
the file. The value n ranges from 18 bytes through 
32K bytes for magnetic tape and 7294 bytes for disc. 


res (Optional) 


CATALOG=|{ na 
CATALOGE=NO specifies that the file should not be 
centrally cataloged. If omitted or CATALOG=YES, 
the file is cataloged. The parameter is ignored for 
scratch and temporary files. 


ot 


NO (Optional) 


con=| 


CON=YES specifies that contiguous space is to be 
obtained. Absence of this parameter or CON=NO 
allows segmentation. 


ve 


CSD= fs 


(Optional) 


CSD=YES (default case) specifies that the file will be 
created with the common stored data format. 
CSD=NO specifies that a data format other than CSD 
will be used. 


YES 
(Optional) 


DATACYL*| NO 
n 


DATACYL=n designates a cylinder number boundary 
for the beginning of the data file. The value n ranges 
from 1 to 199. DATACYL=YES ensures the file 
beginning on some cylinder boundary; whereas 
DATACYL=NO does not. If the parameter is 
omitted, the data file will not necessarily begin on a 
cylinder boundary. 

eRRcOMP=|E>| 


NO (Optional) 


ERRCOMP=YES specifies that the caller of the 
request will examine return information on nonfatal 
errors; therefore, nonfatal errors should not be 
aborted by the system. Fatal errors such as illegal 
instructions, irrecoverable memory parity errors, 
privilege violations, and bound errors cause an 
unconditional abort. If ERRCOMP=NO or is omitted, 
no return information is examined. 


FILEORG=code (Optional) 


Determines the file organization. The possible codes 
are as follows: 


Code Organization 


S Sequential 
R Relative 
| Indexed 


If the code is omitted, sequential file organization is 
used. 
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FILESIZ=n 


Indicates an estimate of the number of blocks 
expected in the data file. 


FILETYP=code (Optional) 


Designates the file type. The possible codes are as 
follows: 


Code Type 
S Scratch 
T Temporary 
W Work 
P Permanent 


If the code is omitted, the temporary file type is 
used. 


IDENT=symbolic address (Optional) 


Designates the 8-character file identifier. It should be 
identical to the operand of the IDENTIFIER 
keyword in a Control Language DEFINE statement 
specifying the volume on which to allocate the file. If 
IDENT does not match the IDENTIFIER 
specification (or if omitted) and the file is to be 
centrally cataloged, the file will be allocated on 
shared resources. IDENT is required if the LABDEF1 
parameter is not specified. 


YES. 
INDCYL={ NO 
n 


(Indexed files only) 


INDCYL=n specifies a cylinder number boundary for 
the beginning of the index file. The value n ranges 
from 1 to 199. INDCYL=YES ensures the file will 
begin on some cylinder boundary; whereas 
INDCYL=NO does not. If the parameter is omitted, 
the index file will not necessarily begin on a cylinder 
boundary. 


INDSIZ=n (Indexed files only) 
Specifies the estimated byte size of the index blocks. 
The value of n ranges from 18 bytes to 7294 bytes. 


KEYSIZ=n (Indexed files only) 
Gives an estimate of the byte length of the primary 
key for indexed files. The value of n ranges from 2 
bytes to 100 bytes. 


LABDEF1=symbolic address 


Specifies the symbolic address of a file label area 
which must correspond to the symbolic address 
specified as the name field of the DEFLB macro. 
LABDEF1 is required if the IDENT parameter is not 
specified. 
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LABDEF2=symbolic address (Optional) 
Specifies a second file label address for paired file 
allocation requests. This option is available for 
sequential and relative files only. 


YES 


NO (Optional) 


LisT-| 


lf LIST=YES, only the parameter packet is generated, 
and the RETURN and ERRCOMP options are not 
used. If LIST=NO, only the 2-byte standard executive 
request instruction is generated. Loading of 
general-purpose register 6 (R6) with the address of 
the parameter packet and general-purpose register 7 
(R7) with the save area address prior to issuing the 
macro call is a user responsibility. If the LIST 
parameter is omitted, both the execution request 
instruction and the parameter packet are generated 
following the macro call. Appendix B contains a 
detailed discussion of the LIST parameter. 


RECSIZ=n 


Indicates the length of a logical record in bytes. The 
value n ranges from 18 bytes through 32K bytes for 
magnetic tape and 7294 bytes for disc. If omitted, 
RECSIZ equals BLKSIZ. 


(Optional) 


RETURN=| v0) | 


NO 


RETURN=YES specifies that the processor issuing 
the executive request should be given control 
(reactivated) as soon as the request is queued to its 
destination routine. If RETURN=NO or if the 
parameter is omitted, the calling processor is 
reactivated when the request processing is complete 
or terminates abnormally if ERRCOMP=YES. 

SPREAD=n (Indexed files only) 
Specifies the number of physical blocks separating 
two logically consecutive blocks in the indexed data 
file. The number of blocks between logically 
consecutive blocks is one less than the n value whose 
range is 1 through 10. If this parameter is omitted, 
the logically consecutive blocks are adjacent. 


(Optional) 


veriry=[YE} 


NO 


VERIFY=YES specifies read after write verification 
of all writes to this file. If omitted or if 
VERIFY=NO, write verification will not be a 
permanent file characteristic. The VERIFY=YES 
option may be specified as a temporary override 
through logical level file definition macros or through © 
Contro! Language DEFINE statements at file open 
time. 


EXPND — Add Mass Storage Space 


The EXPND macro obtains additional mass storage 
space for sequential files. The file may be open but 
cannot have input or update usage at the time of the 
EXPND request. The format is as follows: 


Name Operation Operand 
[tag] EXPND [cataoc-{**} | 
[CON= (not! 
[ ERRCOMP- (no t! 
[FILESIZ=n] 


{IDENT=symbolic address] 
LABIDEF=symbolic address 


[List= (oa) 


rane 


[rerurn-(¥E5} | 


CATALOG= {es YES 


(Optional) 


CATALOG=NO specifies the file is not centrally 
cataloged. If the parameter is omitted or 
CATALOG=YES, the file is centrally cataloged. The 
parameter is ignored for scratch or temporary files. 


(Optional) 


con=|re| 


NO 


CON=YES specifies addition of contiguous space. If 
absent or CON=NO, segmentation is allowed within 
the space added. 


(Optional) 


ERRCOMP=| V0 | 


NO 


ERRCOMP=YES specifies that the caller of the 
request will examine return information on nonfatal 
errors; therefore, nonfatal errors should not be 
aborted by the system. Fatal errors such as illegal 
instructions, irrecoverable memory parity errors, 
privilege violations, and bounds errors cause an 
unconditional abort. lf ERRCOMP=NO or if omitted, 
no return information is examined. 


FILESIZ=n (Optional) 


Indicates the number of blocks to add to the file. 
IDENT=symbolic address (Optional) 


Specifies the 8-character file identifier. If the file is 


open at the time of expansion, it must match the 
name specified by the IDENT parameter of the OPEN 
macro. If the file is closed, it should match the 
operand of the IDENTIFIER keyword in a Control 
Language DEFINE statement specifying a volume 
identifier for expansion. If IDENT does not match 
the IDENTIFIER specification (or if omitted) and 
the file is centrally cataloged, the expansion will be to 
the shared device. IDENT is required if LABDEF is 
not specified. IDENT may be omitted only for 
cataloged files. 


LABDEF=symbolic address 


Specifies the symbolic address of a file label which 
must be identical to the label address of the DEFLB 
macro. This parameter is required if the IDENT 
parameter is not specified. 


Med (Optional) 


NO 


lf LIST=YES, only the parameter packet is generated, 
and the RETURN and ERRCOMP options are not 
used. If LIST=NO, only the 2-byte standard executive 
request instruction is generated. Loading of R6 with 
the address of the parameter packet and R7 with the 
save area address prior to issuing the macro call is a 
user responsibility. If the LIST parameter is omitted, 
both the executive request instruction and the 
parameter packet are generated following the macro 
call. Appendix B contains a detailed discussion of the 
LIST parameter. 


List| 


PAIRED=| v6, | 


NO (Optional) 


PAIRED=YES indicates the file is paired. If 
PAIRED=NO or if the parameter is omitted, there is 
no pairing of files. 


(Optional) 


RETURN=YES specifies that the processor issuing 
the executive request should be given control 
(reactivated) as soon as the request is queued to its 
destination routine. If RETURN=NO or if the 
parameter is omitted, the calling processor is 
reactivated when the request processing is complete 
or terminates abnormally if ERRCOMP=YES. 


PURGE — Release Disc File Space 


The PURGE macro releases the space allocated to a 
disc file. For paired file allocation, both files are 
purged. The format is as follows: 
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Name Operation Operand 

[tag] PURGE [catacoc-{*5*} ] 
[ ERRCOMP= Fema 
Het ROME address] 
LABDEF=symbolic address 
[List={Ne>} ] 
[PAIRED= ea} 
[RETURN= fie ai 

caTaLo~(¥F° (Optional) 


CATALOGENO specifies that the file is not centrally 
cataloged. If the parameter is omitted or 
CATALOG=YES, the file is cataloged. The parameter 
is ignored for scratch and temporary files. 


ER RCOMP=| 0) | 


NO (Optional) 


ERRCOMP=YES specifies that the caller of the 
request will examine return information on nonfatal 
errors; therefore, nonfatal errors should not be 
aborted by the system. Fatal errors such as illegal 
instructions, irrecoverable memory parity errors, 
privilege violations, and bounds errors cause an 
unconditional abort. If ERRCOMP=NO or if omitted, 
no return information is examined. 
IDENT=symbolic address (Optional) 
Specifies the 8-character file identifier. It must match 
the operand of the IDENTIFIER keyword in a 
Control Language DEFINE statement specifying the 
volumes of the file purge. IDENT may be omitted 
only for cataloged files. If omitted, Data Management 
finds the file in the central catalog and then locates 
the volumes. 


LABDEF=symbolic address 


Specifies the address of a file label, which must 
correspond to the label address of the DEFLB macro. 
This parameter is required if the IDENT parameter is 
not specified. 


Neg 


LIST= | NO 


(Optional) 


If LIST=YES, only the parameter packet is generated, 
and the RETURN and ERRCOMP options are not 
used. If LIST=NO, only the 2-byte standard executive 
request instruction is generated. Loading of R6 with 
the address of the parameter packet and R7 with the 
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save area address prior to issuing the macro call is a 
user responsibility. If the LIST parameter is omitted, 
both the executive request instruction and the 
parameter packet are generated following the macro 
call. Appendix B contains a detailed discussion of the 
LIST parameter. 


(Optional) 


PAIRED=| v0) | 


NO 


PAIRED=YES indicates the file is paired. If the 
parameter is omitted or PAIRED=NO, the file is not 
paired. 


(Optional) 


RETURN| 4 | 


NO 


RETURN=YES specifies that the processor issuing 
the executive request should be given control 
(reactivated) as soon as the request is queued to its 
destination routine. If RETURN=NO or is omitted, 
the calling processor is reactivated when the request 
processing is complete or terminates abnormally if 
ERRCOMP=YES. 


FILE CONTROL 


The file control macros — OPEN, CLOSE, and 
CLOVE — direct data transmission. OPEN and 
CLOSE control a file or unit at the block or physical 
1/O level. CLOVE performs volume switching at the 
block I/O level. 


OPEN — Open File for Data Transmission 


The OPEN macro makes the file or unit assessible for 
data transmission. The format is as follows: 


Name Operation Operand 
[tag] OPEN [ BUFADR=symbolic address ] 


[ CONTROL= (es) ] 
[ eRRcoMP={\ >} ] 
‘IDENT=symbolic address 


forve-{°}] 


[LABDEF=symbolic address] 


[ust=(\o t 


[ReTURN={\0 }] 


[Rewinp={<E*} ] 


[usace-{u}} 


BUFADR=symbolic address (Optional) 


Specifies the address of a buffer for use in initiating a 
file. BUFADR is required when USAGE=O for block 
1/0 level openings of a relative file. The user generates 
the desired data as dummy data in this buffer prior to 
the OPEN request. The initialization is performed 
only once. BUFADR is required if IOTYP=P. 


0 Unit ordinal = Length 

2 Unit Table Word 1 

4 Unit Table Word 2 

6 

8 Volume Id 

° ST 

CONTROL -( ANS | (Optional) 


CONTROL=NATIVE indicates that the control 
characters are native to that particular device. ANSI 
control characters are used if it is omitted or 
CONTROL=ANS. 


ERRCOMP-| 


ie 


NO (Optional) | 


ERRCOMP=YES specifies that the caller of the 
request will examine return information on nonfatal 
errors; therefore, nonfatal errors should not be 
aborted by the system. Fatal errors such as illegal 
instructions, irrecoverable memory parity errors, 
privilege violations, and bounds errors cause an 
unconditional abort. If ERRORCOMP=NO or is 
omitted, no return information is examined. 


IDENT=symbolic address 


Specifies the 8-character file identifier. IDENT must 
be identical to the operand of the IDENTIFIER 
keyword in a Control Language DEFINE statement. 


B (Optional) 


lOTYPs| e 
Determines the type of 1/0. l|OTYP=P for physical 
open: IOTYP=B (block open) creates the FDT for 
block 1/0. The default value is B. If IOTYP=P, then 
BUFADR must be specified. 


LABDEF=symbolic address 


Specifies the address of a main-storage buffer that 
contains a file label. The symbolic address should be 


identical with the label address name specified in the 
DEFLB macro. This parameter is ignored for files on 
unit record or magnetic tape (tape labels are assigned 
by the control language). For disc files, label 
information may have been specified by Control 
Language DEFINE statements which override 
LABDEF information. For temporary or scratch files, 
the file name is concatenated with the job name. 


ust=("E5| 


NO (Optional) 


If LIST=YES, only the parameter packet is generated, 
and the RETURN and ERRCOMP options are not 
used. !f LIST=NO, only the 2-byte standard executive 
request instruction is generated. Loading of R6 with 
the address of the parameter packet and R7 with the 
save area address prior to issuing the macro call is a 
user responsibility. If the LIST parameter is omitted, 
both the executive request instruction and the 
parameter packet are generated following the macro 
call. Appendix B contains a detailed discussion of the 
LIST parameter. 


(Optional) 


RETURN=YES specifies that the processor issuing 
the executive request should be given control 
(reactivated) as soon as the request is queued to its 
destination routine. If RETURN=NO or is omitted, 
the calling processor is reactivated when the request 
processing is complete or terminates abnormally if 
ERRCOMP=YES. 


od (Optional) 


REWIND={YES 


REWIND=NO indicates that no initial rewind of 
magnetic tape files is to be performed. If 
REWIND=YES or is omitted, initial rewind is 
performed. 


USAGE= 4 U 
O 


(Optional) 


Specifies input (1), update (U), or output (O) 
processing. Update usage is allowed for sequential 
files only if the record type is fixed length and the 
file is assigned to mass storage. The default value is |. 


CLOSE — Close File for Data Transmission 


The CLOSE macro removes the availability of the file 
for data transmission. The format is as follows: 
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Name Operation Operand 


el 


[tag] CLOSE [ ERRCoMP={ 


IDENT=symbolic | address 


llorve-(5}] 
[ List={“E5}} 


[ Lock=(\5'] 


[ RETURN= Mag) 


[ Rewino-{¥ES}} 


(Optional) 


ER ncome=|¥F°| 


NO 


ERRCOMP=YES specifies that the caller of the 
request will examine return information on nonfatal 
errors; therefore, nonfatal errors should not be 
aborted by the system. Fatal errors such as illegal 
instructions, irrecoverable memory parity errors, 
privilege violations, and bounds errors cause an 
unconditional abort. lf ERRCOMP=NO or is omitted, 
no return information is examined. 


IDENT=symbolic address 


Specifies the 8-character file identifier. It must be 
identical to the one specified in the OPEN macro. 


joTyP=| és (Optional) 


Indicates the type of I/O. IOTYP=P for physical 
close. |OTYP=B (block close) releases the FDT. The 
default value is B. 


List=| | 


NO (Optional) 


lf LIST=YES, only the parameter packet is generated, 
and the RETURN and ERRCOMP options are not 
used. If LIST=NO, only the 2-byte standard executive 
request instruction is generated. Loading of R6 with 
the address of the parameter packet and R7 with the 
save area address prior to issuing the macro call is a 
user responsibility. If the LIST parameter is omitted, 
both the executive request instruction and the 
parameter packet are generated following the macro 
call. Appendix B contains a detailed discussion of the 
LIST parameter. 


Lock-| il 


NO (Optional) 


Specifies the disposition of the file. When 
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LOCK=YES is used, the FDT is flagged and OPEN 
may not be executed again during the same job; files 
assigned to magnetic tape are unloaded. When this 
parameter is not used or LOCK=NO, the file may be 
reopened from within the same job; files assigned to 
magnetic tape may be rewound. 


RETURN-( ed 


NO (Optional) 


RETURN=YES specifies that the processor issuing 
the executive request should be given control 
(reactivated) as soon as the request is queued to its 
destination routine. If RETURN=NO or is omitted, 
the calling processor is reactivated when the request 
processing is complete or terminates abnormally if 
ERRCOMP=YES. 


(Optional) 


REWIND=NO specifies that magnetic tape files are 
not rewound after closing. If the parameter is omitted 
or REWIND=YES, the tapes are rewound/unloaded. 


CLOVE — Close Volume 


The CLOVE macro performs volume switching at the 
block 1!/O level. It is used for sequential multivolume 
files assigned to tape or disc. A user program may 
close a volume at any time and switch to the next 
sequential volume. CLOVE must be used when a 
switch to the next volume is indicated by either an 
EOF record or an end of space indicator from block 
1/0. 


CLOVE performs header and trailer label processing 
on tapes, alternate unit processing on tapes, and disc 
pack mounting and. dismounting (via operator 
control). The format is as follows: 


Name Operation Operand 
[tag] CLOVE [errcom={1.6} ] 


IDENT=symbolic ¢ address 
YES 
[ust-{o}] 


[ RETURN= io) ] 


YES 


ERRCOMP= Ne (Optional) 


ERRCOMP=YES specifies that the caller of the 
request will examine return information on nonfatal 
errors; therefore, nonfatal errors should not be 
aborted by the system. Fatal errors such as illegal 
instructions, irrecoverable memory parity errors, 
privilege violations, and bounds errors cause an 
unconditional abort. lf ERRCOMP=NO or is omitted, 
no return information is examined. 


IDENT=symbolic address 


Specifies the 8-character file identifier. 
YE 
| (Optional) 


List=| XE 


lf LIST=YES, only the parameter packet is generated, 
and the RETURN and ERRCOMP options are not 
used. If LIST=NO, only the 2-byte standard executive 
request instruction is generated. Loading of R6 with 
the address of the parameter packet and R7 with the 
save area address prior to issuing the macro call is a 
user responsibility. If the LIST parameter is omitted, 
both the executive request instruction and the 
parameter packet are generated following the macro 
call. Appendix B contains a detailed discussion of the 
LIST parameter. 


(Optional) 


RETURN=YES specifies that the processor issuing 
the executive request should be given control 
(reactivated) as soon as the request is queued to its 
destination routine. If RETURN=NO or if the 
parameter is omitted, the calling processor is 
reactivated when the request processing is complete 
or terminates abnormally if ERRCOMP=YES. 


i/O SERVICE MACRO 


Data Management also has available I/O service 
macros which can report the status information of 
various aspects of the file. 


LABRTN — Return File Label Information 


The LABRTN macro returns the disc catalog 
elements for uncataloged and cataloged files. The file 
may be open or closed. LABRTN searches the FDT 
string in partition first; and if there is no FDT, 
LABRTN then searches the table created by the 
Control Language DEFINE statement. If the IDENT 
is found, then the proper disc file information is 
returned in the buffer specified by the user in 
INFOADR. If a LABRTN macro is issued against a 
nondisc device and the IDENT specification matches 
a Control Language //DEFINE statement. for a 
nondisc device, LABRTN returns an error code and 
returns the device type in the first byte of the user 
buffer. The format is as follows: 


Name Operation Operand 
NAME 
[tag] LABRTN [ eLEMENT-[ATTRIBUTE ] 
ALL 
_sYES 
[ ERRCOMP= NO \ 


tDENT=symbolic address 
tNFOADR=symbolic address 


_sYES 
[ uist=(6 } 
_jYES 
[ RETURN= NO } ] 
NAME 
ELEMENT =; ATTRIBUTE (Optional) 
ALL 


Specifies that the name element, attribute element, or 
both elements will be returned in the buffer specified 
by INFOADR. !f the parameter is omitted, the 
NAME element is returned. If ELEMENT=ALL is 
specified, the name and attribute elements are 
returned respectively. For an indexed file, the data 
portion of the file is returned first and then the index 
portion of the file. 


eg (Optional) 


ER RCOMP=| VE 


ERRCOMP=YES specifies that the caller of the 
request will examine return information on nonfatal 
errors; therefore, nonfatal errors should not be 
aborted by the system. Fatal errors such as illegal 
instructions, irrecoverable memory parity errors, 
privilege violations, and bounds errors cause an 
unconditional abort. If ERRCOMP=NO or if omitted, 
no return information is examined. 


IDENT=symbolic address 


Specifies the 8-character file identifier which was 
used to open the file. 


INFOAD R=symbolic address 


Specifies the address of a main-storage buffer where 
the information is returned. 


a 


uist={" . (Optional) 


If LIST=YES, only the parameter packet is generated, 
and the RETURN and ERRCOMP options are not 
used. If LIST=NO, only the 2-byte standard executive 
request instruction is generated. Loading of R6 with 
the address of the parameter packet and R7 with the 
save. area address prior to issuing the macro call is a 
user responsibility. If the LIST parameter is omitted, 
both the executive request instruction and the 
parameter packet are generated following the macro 
call. Appendix B contains a detailed discussion of the 
LIST parameter. 
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RETURN=|ve| 


NO Optional 


RETURN=YES specifies that the processor issuing 
the executive request should be given control 
(reactivated) as soon as the request is queued to its 
destination routine. If RETURN=NO or if the 
parameter is omitted, the calling processor is 
reactivated when the request processing is complete 
or terminates abnormally if ERRCOMP=YES. 


BLOCK INPUT/OUTPUT MACROS 


READ 


This macro transfers a block of data into the specified 
buffer. If the location of the block is not explicitly 
stated in the request, it will be generated by adding 1 
to the block number last obtained (this applies to disc 
and tape files only). If the preceding reference to this 
file involved a WRITE or POSITN request, the 
current block number is used without updating. When 
the BLKNUM keyword is not used, the file is 
addressed in a sequential manner. 


Standard error recovery is provided, with 
irrecoverable errors terminating the operation and 
posting the return code in the request block. 
Attempts to read outside of the portion of the file 
which is currently accessible (current volume) will 
result in an error. 


Name Operation Operand 


[tag] READ IDENT=symbolic address 


DATBUF=symbolic address 
[DATSIZ=symbolic address] 


[uist=(NE°}] 


[ReTURN={V0 | ] 
[errcomp={, >>} ] 


YES 
[escoic={- =} 
[OPER=SSn] 
[BLKNUM=symbolic address] 

_sYES 
[MULTBLK={\,, }] 
IDENT=symbolic address 


Specifies the address of a storage location containing 
the file identifier — the name by which the file is 
known to the program (as opposed to the external 
catalog name specified through Control Language). 
The file identifier must be eight bytes in length. 


DATBUF=symbolic address 


The address of the data buffer. Requests to disc 
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storage must specify a buffer which begins and ends 
on word boundaries even though the data count may 
be odd. 


DATSIZ=symbolic address Optional 
An address pointer to the number of bytes in the 
buffer. If this is omitted, the block size defined for 
the file is used as the byte count. The buffer size may 
be up to 65,535 bytes. Any DATSIZ value given 
which is greater than the device record size will result 
in a nonzero residual count returned at the end of the 
operation. 


List| Optional 


YES 
NO 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


Optional 


RETURN={6 | 


NO 


To be used when the user program wishes to be given 
control immediately on recognition of the request, 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 


request. 


ERRCOMP-| a 


NO Optional 
To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMPENO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


The following parameters apply to the card reader 
only. 


YES 
EBCDIC= | NO Optional 


This determines the type of conversion to be 
performed on the data between card format and 
memory format. If EBCDIC=YES, the translation is 
made in accordance with the defined EBCDIC 
formats. If EBCDIC=NO, the data on the card is 
accepted in a binary format and is transferred to 
storage without modification (card image storage 
format, shown in Figure 7-1). If the parameter is 
omitted the EBCDIC=Y-ES option is assumed. 
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Figure 7-1. Card Image/Storage Relationship 


OPER=SSn Optional 


Selects a stacker for the card read, designated by n. 
The value n is determined by the hardware device 
being used. This parameter is ignored except for card 
readers with multiple stackers. If it is omitted, the 
normal stacker is used. 


The following parameter applies to magnetic tape and 
disc files only. 
BLKNUM=address Optional 
The address of a four-byte hexadecimal field 
containing the block number to be read. If it is 
omitted, the current block number of the file is 
updated by 1 before the READ, unless the last 
operation was a WRITE* or POSITN, in which case 
the current block number is used. Block numbers up 
to 232.1 are allowed, but attempts to read beyond 
the limits of a file (as defined by allocation) are 
returned with return information noted. 


Block numbers up to 232.4 are allowed, but attempts 
to read beyond the limits of a file (as defined by 


allocation) are returned with return information 
noted. 

_}YES : 
MULTBLK= | VE (Optional) 


If this operand is specified, as many disc records as 
the program buffer will hold will be loaded. Any 
remaining buffer space will be noted in the residual 
count field. 


*READ after WRITE on magnetic tape is illegal. 


WRITE 

This macro transfers a block of data from the 
specified buffer to an I/O device. The location on the 
1/O device where the data is to be placed may be 
controlled by the BLKNUM keyword (disc), or the 
current setting of the file block number will be used. 
In either case, the file block number is updated after 
the WRITE operation by adding 1 to the current 
block number. 


When writing to the line printer or card punch, the 
first character of the user’s buffer is used for carriage 
or stacker control, and is deleted from the data line. 
This feature may be overridden by the OPER option. 
The first character of the buffer is still deleted from 
the line. 


Errors detected by the 1/O routines initiate error 
recovery procedures. If these fail to correct the error, 
the return code is posted in the request block and the 
operation is terminated. 


Name Operation Operand 
[tag] WRITE IDENT=symbolic address 


DATBUF=symbolic address 
[DATSIZ=symbolic address] 


fusr=(Ye>} 
[ RETURN-{ Ve | 


YES 
[ ERRCOMP={/" } | 


YES 

[ epcpice{¥= } | 

{[BLKNUM#symbolic address] 
SKnn 

[ oren-| rm | 


$Sn 


IDENT=symbolic address 


Specifies the address of a storage location containing 
the file identifier — the name by which the file is 
known to the program (as opposed to the external 
catalog name specified through Control Language). 
The file identifier must be eight bytes in length. 


DATBUF=symbolic address 


Specifies the address of the data buffer. Requests to 
disc must specify a buffer which begins a word 
boundary. 


DATSIZ=symbolic address Optional 


The address of the memory word which contains the 
byte count of the buffer. If it is omitted, the block 
size defined for the file is used as the byte count. The 
buffer size may be up to 65,535 bytes. 


ee Optional 


List={¥F 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


Optional 


RETURN=( 46 | 


NO 


To be used when the user program wishes to be given 
control immediately on recognition of the request, 
but before completion (RETURN=YES). When 
RETURN=NO is added, or the default is taken, 
control will only be returned on completion of the 
request. 


ER RCOMP=| Optional 


YES 
NQ. 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMPE=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


Magnetic Tape and Disc 

BLKNUM=symbolic address Optional 
The address of a four-byte hexadecimal field 
containing the block number to be read. This 
parameter is valid only for direct-access storage 


devices. If it is omitted, the current block number of 
the file is updated by 1 after the WRITE operation. 
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Block numbers through 232.1 are allowed, but 
attempts to write beyond the limits of a file (as 
defined by allocation) are returned with an error 
indication. 


Line Printer 
OPER=SKnn Optional 


Defines a carriage control tape channel to be used 
when the data is written by a line printer. If the file is 
not a printer file, the value of nn is converted to a 
comparable ASA standard control character which 
overlays the first character of the written block. If 
the file is a printer file, this parameter overrides the 
carriage operation specified by the first character of 
the data record. Regardless of the method used, the 
first character in the data buffer is deleted from the 
print fine. 


OPER=SPnn Optional 


Defines the number of print lines to be spaced after 
printing. It is treated in a manner like that of the 
OPER=SKnn parameter. From 1 to 15 lines may be 
specified depending on hardware capabilities. 


Card Punch 
OPER=SSn Optional 


Defines a stacker select operation to a card punch. If 
this parameter is used, the first character in the data 
buffer is written in the first position of the card. If 
the parameter is not used, the first character in the 
data buffer is treated as a stacker select code and is 
deleted from the punch data. The absence of multiple 
stackers on the card punch has no effect on this 
procedure. 


YES 


escpic=|*E 


Optional 


This determines the type of conversion to be 
performed on the data between card format and 
memory format. With EBCDIC=YES, the translation 
is made in accordance with the defined EBCDIC 
formats. With EBCDIC=NO, the data on the card is 
treated as being in a binary format (card image) and is 
transferred from storage without modification 
(Figure 7-1). If the parameter is omitted the 
EBCDIC=YES option is assumed. 


POSITN — Change Current Block Number 


The POSITN request is used to change the current 
block number for the file. The subsequent READ or 
WRITE macro begins processing at the new block 
number. POSITN is only allowed for files assigned to 
disc storage or magnetic tape. 


A POSITN on a magnetic tape file will always cause 
the tape to be physically repositioned, whereas with 
disc files a physical seek operation will not be 
performed unless explicitly requested by SEEK=YES. 


Narne Operation Operand 


[tag] POSITN IDENT=symbolic address 


BOV 
BLKNUM=;EOV 
[Btwn | 
symbolic:address 
[ List={ VES} } 


NO 
YES 
[ RETURN No } 


YES 
[ ERRCOMP={ 16 hy 


YES 
| 


[ SEEK={\6 


IDENT=symbolic address 


Specifies the address of a storage location containing 
the file identifier — the name by which the file is 
known to the program (as opposed to the external 
catalog name specified through Control Language). 
The file identifier must be eight bytes in length. 


BOV 
BLKNUM=4EOV Optional 
symbolic address 


Specifies the block number at which the file is to be 
positioned. BOV indicates beginning of volume, EOV 
indicates end of volume”. If a symbolic address is 
coded this is taken as the address of a four-byte field 
containing the block number as an_ unsigned 
hexadecimal number. 


if this parameter is omitted, a position to BOV is 
performed. Standard error recovery is provided, with 
irrecoverable errors terminating the operation and 
posting the exception indicator and return code in 
the request block. A POSITN to block number 1 is a 
request to position at the beginning of the file. A 
POSITN to block number 0 will return an error. A 
position to a block number above the highest block 
currently mounted will also be returned with an 


error; however, the file will be left positioned on the 


last block of the volume or file. 


| Optional 


List-{¥5 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
*For magnetic tape EOV indicates a position forward to the 
first tapemark. For disc, BOV and EOV result in 
positioning, across physical pack boundaries if necessary, to 
the lowest (BOV) or highest (EOV} block number which is 
currently described in the File Description Table. 


request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 

RETURN=(X0, | 


NO Optional 


To be used when the user program wishes to be given 
control immediately on recognition of the request, 
but before completion (RETURN=YES). When 
RETURN=NO is added, or the default is taken, 
contro! will only be returned on completion of the 
request. 


ERRCOMP=| Ve | 


NO 


To be used when the user devices to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMP=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


Optional 


The following description applies only to disc storage. 


Optional 


seek-(t5 | 


NO 


This parameter causes the disc drive arm to be 
physically positioned on the cylinder in which the 
specified block number is to be found. If the 
parameter is omitted, the seek operation will be 
performed when the following READ or WRITE 
macro is executed and the POSITN will merely 
update the block number. 


SEEK=YES should only be included when operating 
on an unshared file; this is because the position of the 
disc arm is not locked after a POSITN macro has been 
executed, and with a shared file the arm could 
therefore be repositioned by another user before data 
transfer had begun. If the SEEK on POSITN 
capability was not included in the operating system 
(SYSGEN), this operand is ignored. 


CNTRL — Hardware Control Operation 


The CNTRL request is used to perform a specific 
hardware control operation (this does not apply to 
spooled files going to disc storage). The operations 
allowed are dependent upon the device type. 
Standard error recovery is provided, with 
irrecoverable and logical errors terminating the 
operation and posting the return code in the request 
block. Control of the internal block number is 
maintained where possible, but if an operation is 
performed which does not maintain the block 
number, any subsequent request which needs a block 
number will be terminated with an error. 
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Name Operation Operand 


IDENT=symbolic address 
[ ist-{¥es| | 


NO 
YES 
[ RETURN={ 6 } 


{YES 
[| ERRCOMP= NO | 


OPER=operation code 


[tag] CNTRL 


IDENT=symbolic address 


Specifies the address of a storage location containing 
the file identifier — the name by which the file is 
known to the program (as opposed to the external 
catalog name specified through Control Language). 
The file identifier must be eight bytes in length. 

List-{ "5 | 


NO Optional 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


Optional 


To be used when the user program wishes to be given 
control immediately on recognition of the request, 
but before completion (RETURN=YES). When 
RETURN=NO is added, or the default is taken, 
control will only be returned on completion of the 
request. 


YES 


NO Optional 


ERRCOMP=| 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMP=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


OPER=operation code 


e Reader/Punch 
OPER=SSn 


Select stacker on a card reader/punch. 
The numeric value of 7 is the stacker 
number. This command may only follow 


e Line Printer 


OPER=SPnn 


Space the printer form nn lines 
immediately. From 1 to 15 lines may be 
specified, depending on the hardware 
capability. 


OPER=SKnn 


Skip to carriage control tape channel nn 
immediately. 


The permissible values of nn are 1 
through 12, corresponding to channels 1 
through 12 of the printer carriage 
control. 


e@ Magnetic Tape 


OPER=REW 


Rewind tape. The internal block number 
will not be maintained. 


OPER=RUN 


Rewind and unload tape. The block 
number will not be maintained. 


OPER=ERG 


Erase gap (write blank tape). The block 
number will be maintained. 
OPER=BSR 


Backspace to interrecord gap. The block 
“number will be maintained. 


OPER-FSR 


Forward space to interrecord gap. The 
block number will be maintained. 


OPER=FSF 


Forward space to tapemark (EOF). The 
block number will not be maintained. 


OPER=BSF 


Backspace to tapemark (EOF) or to Load 
Point if no tapemark is present. The 
block number will not be maintained. 


OPER=EOF 


Write End-of-File mark (tapemark). The 
block number will be maintained. 


e Disc Files 


OPER=EOF“ 


Write End-of-File mark (a record 
containing a count field specifying a data 
length of zero). When read, this record 


7-14 


a READ to a file opened for modify 
usage. 


*For disc, CNTRL will always write an EOF mark regardless 
of whether the OPER=EOF operand is included or not. 


will cause the system to set the EOF flag 
in the request block and in the File 
Description Table. The block number will 
be maintained. 


STATUS — Report of Status 


This request causes the system to pass information to 
a specified data buffer regarding the status of the file 
at the completion of the last operation to the file. 


Name Operation Operand 


IDENT=symbolic address 
BUFADR=symbolic address 
BUFSIZ=symbolic address 


Fusr=(%) 


[ RETURN={ 


[tag] STATUS 


ng 


YES 
[ ERRCOMP={ } ] 


IDENT=symbolic address 


Specifies the address of a storage location containing 
the file identifier — the name by which the file is 
known to the program (as opposed to the external 
catalog name specified through Control Language). 
The file identifier must be eight bytes in length. 


BUFADR=symbolic address 


Specifies the address of the data buffer. 


BUFSIZ=symbolic address 


Specifies the address of the memory word containing 
the byte count of the buffer. 


uist=("E5} 


NO Optional 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


YES : 
RETURN=| 5 Optional 


To be used when the user program wishes to be given 
control immediately on recognition of the request 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


Optional 


enncomP-|Ve| 


NO 


To be used when the user decides to retain control} in 
the event of an error (ERRCOMP=YES). When 
ERRCOMP=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


Between 20 and 24 bytes of file status information 
are available from the system, depending on the type 
of device (Table 7-1). The BUFSIZ specification 
determines how much of this information is to be 
returned, starting from the top of the table (this 
could be less than the total amount available, if 
specified). 


Table 7-2 gives the information for the status word of 
the Basic Data Channel! operation; Table 7-3 gives the 
status word for Disc Channel operation. 


TYPE — Device and File Type 


This request causes the system to pass two bytes of 
information to the data buffer regarding the type of 
file and the type of device for which this file is 
prepared. 


Name Operation Operand 


[tag] TYPE IDENT=symbolic address 


BUFADR=symbolic address 


Cust) 


[ Return={ iO} ] 


[ enrcomp={\C>} ] 


IDENT=symbolic address 


Specifies the address of a storage location containing 
the file identifier — the name by which the file is 
known to the program (as opposed to the external 
catalog name specified through Control Language). 
The file identifier must be eight bytes in length. 


BUFADR=symbolic address 


Specifies the address of the data buffer. 
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Table 7-1. Returned Information Format 


UD L SF | Last BIO Function 


Current Block Number 


Error Field 


Block Size 


Pointer to Current Command Word 


Status of Last 1/O Operation 


Residual Count 


Disc: 


No. of Residual Blocks 


Highest Block Written (per volume) 


Magnetic Tape: 


20 Sense 


Unit Record: 


18 | Sense | Unit Ordinal | 


Table 7-1. Returned Information Format (Continued) 


Field Name 


Common stored data format flag (C) 


Usage Flag (US) 


Bypass Flag (B) 


Update Flag (US) 
Lockout Flag (L) 
Sequential File Flag (SF) 


Last BIO Function 


Current Block Number (four bytes) 


Error Field 


System Error Processing (EP) 


Not Used 


FDT Restore (FR) 


Hold Up Flag (H) 


Not Used 
Not Used 


Block Size 


not common stored data format 


common stored data format 


input 
update 


output 


no bypass 


bypass: 
READ goes to EOF 
WRITE is a NOP 


not update mode 


update mode 


no lockout 


file has been closed with lock 


_ hot sequential 


1 sequential 


Last function processed in BIO 


Block number after last function processed. If zero, current 
block number is unknown 


When this field is non-zero, a RESET macro must be issued 


before making another request to the file 


Calt Error Recovery when an error is encountered 


Bypass Error Recovery 


FDT not restored 


FDT restored 


Set when file is in error recovery to prevent further requests 
from being serviced 


Number of bytes in a physical record 
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Table 7-1. Returned Information Format (Continued) 


Field Name 


12,13 


Current CW Pointer 


Status 


Residual Count (RC) 


Not Used 


Paired File Flag (PF) 


Paired File Indicator (PA) 


Write Check (WC) 


Disc Driver Flag 


Not Used 


Residual Blocks 


Magnetic Tape 


18-23 Sense 


Unit Record 


Unit Ordinal (UORD) 


Highest Biock Written (HBW) 


Definition 


Address of the current or last command word executed on 
this file 


Status of last 1/O operation (see Tables 7-2 and 7-3) 


The difference between the number of bytes requested and 
the number of bytes transferred 


Q = not paired 


1 = paired 


O = first track of paired tracks 


1 = second track of paired tracks 


0 = no write check 


1 = write check on all writes 


Used internally by the driver only 


Number of blocks remaining to be set up fofa multiblock 
read request which crosses tracks 


Highest block number written for volume now mounted 


Sense bytes of the device at time of last error 


Sense byte of the device at time of last error 


Unit table ordinal 


Bit Set to 1 


Table 7-2. Status Word for Basic Data Channe! Operations 


Attention 

Status Modifier 
Control Unit End 
Busy 

Channel End 
Device End 

Unit Check 


Unit Exception 


Initial selection sequence error, caused by one of the following: 
Unit not there 
Parity error on bus out 
Bad address 


Unit off-line 


Main storage buffer not exhausted 


Wrong Address-!n returned on initial selection or bad parity on ‘ADDRESS IN’ 


No Request fn on SIO Poll Sequence Request 
Control check 

Examine check (for data transfer only) 
Invalid command or zero byte count 


Unused 
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Table 7-3. Status Word for Disc Channel Operations 


Bit Set to 1 Meaning 


IFA status not valid or command early 
IFA missed window or command early 
{FA window 


IFA track boundary 


IFA read/write terrnination 
IFA burst check error 
IFA lost data 


IFA no-sync compare 


IFA 3rd rev sync find 

Disc (not on line) or (seek incomplete and not file unsafe) 
Disc (file unsafe) or (seek incomplete and not file unsafe) 
Disc read only 

Disc pack change 

Disc end of cylinder 

Disc write current sense or search fail (may be EOF) 

Disc busy 


All bits set Invalid function code in command program 
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List=(\} 


NO Optional 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


. Optional 


RETURN-(\5 | 


NO 


To be used when the user program wishes to be given 
control immediately on recognition of the request 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


Optional 


ER RCOMP=| Vr | 


NO 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMP=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


The system responds to a TYPE request by placing 
two bytes of file information in the buffer in the 
following format: 


0123 45 67 8 15 


Device Type | 


The first byte of this word is the same as the first 
byte returned by the STATUS macro. The second 
byte is a value representing the device type as defined 
following: 


OF-2F input/output devices 
20-3F input only devices 
40-5F output only devices 
60-7F - input/output devices 
80-F F communications devices 


A rnore specific description of the bit significance in 
the device type code is illustrated in Table 7-4. 


RESET — Reset Exception Conditions 


The RESET request allows a user to reset exception 
conditions in the file description table. The exception 
conditions lock out new !/O operations which would 
overlay the exception status indications. Examples of 
exception conditions are EOF and _ irrecoverable 
hardware conditions. 


Name Operation Operand 
{tag] RESET IDENT=symbolic address 


[uist-{VES}] 


[ReTuRN={K6 | ] 


[enrcomp-{i6 } ] 


IDENT=symbolic address 


Specifies the address of a storage location containing 
the file identifier — the name by which the file is 
known to the program (as opposed to the external 
catalog name specified through Control Language). 
The file identifier must be eight bytes in length. 


Optional 


_{YES 
ust=|¥F | 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


Optional 


RETU AN-| ea 


NO 


To be used when the user program wishes to be given 
control immediately on recognition of the request, 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


aT Optional 


ERRCOMP=| VE 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 


ERRCOMP=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 
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Table 7-4. Bit Significance 


Bit assignment 

Card Reader/Punches 
Card Readers 

Card Punches 

Line Printers 
Magnetic Tape Units 
Disc Drives 


Communications Devices 


x = modifier bit 
a = 1 means hardware-buffered device 
b = 1 means early termination (on channel end rather than device end) 


PHYSICAL INPUT/OUTPUT MACROS 


EXCP — Input/Output Action 


Name Operation Operand 
_f@register number 
[tag] REP [Pcs a address y 


_ J @register pepe 
[cP ae address ] 


[UNOR D=symbolic address | 


[ retuan~{veo}] 


[ enncomp-("ES} ] 


This is the physical I/O action macro (the “do 1/0” 
macro). Basically, it generates the service request 
necessary to execute a command program in 
conjunction with a Physical Control Block (PCB) and 
for this purpose does not necessarily require any 
operands. However, it should be noted that two 
preconditions must be satisfied before the EXCP can 
function properly: 


@ general register 6 must be loaded with a 
pointer to the associated PCB 


e the appropriate command program address 
must be loaded into the PCB 


If these two conditions are not already satisfied at the 
time the macro is issued, the following optional 
operands may be included in the macro for this 
purpose. 
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@register number 


: Optional 
symbolic address i 


pce-| 


This operand specifies the address of the PCB. If the 
parameter is omitted, the PCB location is assumed to 
be R6. An alternate register or a symbolic address 
may be designated to give the location of the PCB. 
The use of this keyword causes the contents of R6 to 
be destroyed. 


spain number 


symbolic address Optional 


+ 
+ 


This operand specifies the address of the appropriate 
command program. If this operand is omitted, the 
command program address is assumed to be in the 
PCB. If the keyword is used, a register (other than 
R6) or a symbolic address may specify the location of 
the command program to be executed. If the 
keyword is specified, the address of the command 
program is moved to the CPADR area in the PCB. 


UNORD=symbolic address Optional 


The operand must point to a user location containing 
the unit ordinal of the device on which the operation 
is to be performed. This will normally be the same 
address as the buffer specified in the physical OPEN 
macro associated with the device, since OPEN returns 
this value. 


RETURN -| a Optional 


To be used when the user program wishes to be 
given control immediately on recognition of the 
request, but before completion (RETURN=YES). 
When RETURNE=NO is coded, or the default is 
taken, control will only be returned on completion 
of the request. 


ER RCOMP=| Ko"| Optional 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMP=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


PHYSICAL CONTROL BLOCK 


This is a data macro which generates the Physical 
Command Block necessary for performing a physical 
input/output operation. 


Name Operation Operand 


[tag] PCB {CPADR=symbolic address] 


[ ERROPT={~ES| ] 


TAPE 
[ DevtyP= UREC} | 
DISC 


ca, JASKATT 
L FUNCTN= (pet 
_{YES 
ER ROPT-| NO Optional 


Determines whether system error recovery is to be 
employed in the event that an error occurs when the 
command program is executed (by an EXCP macro), 


MT 


UR : 
DEVTYP= DISC Optional 


COMM 


Determines how much space is to be reserved in the 
generated PCB to receive sense information. 

@ MT reserves three words 

@ UR reserves one word 

e DISC and COMM reserve no space 


© Omitting the DEVTYP operand causes 
reservation of three words 


In the event that an uncorrectable error occurs, sense 
information will always be returned to the PCB and 


the user may then use this information for his own 
error processing provided that ERRCOMP=YES was 
coded in the corresponding EXCP macro. 


CPADR=symbolic address Optional 


This parameter specifies the location of the command 
program to be used with this PCB. The symbolic 
address should be the label used on the command 
program. If this parameter is omitted, the PCB will be 
assembled without a command program address; then 
this address must therefore be supplied dynamically 
at execution time by the corresponding EXCP macro. 


Optional 


FUNCTIN=| AMO VE 


REMOVE 


This optional parameter is used for executing 
functions which do not require a command program. 
When this parameter is coded the CPADR parameter 
is not required and will be ignored if present. 
FUNCTN=ASKATT causes the program to wait for 
an asynchronous attention from the device (such as 
disc pack change, line printer ready, magnetic tape 
loaded). If no attention is received following a 
FUNCTN=ASKATT request, the outstanding request 
must be cleared before the end of the job by issuing a 
FUNCTN=REMOVE request. FUNCTN=REMOVE 
clears all ASKATT requests from the particular device 
and returns them with an explanatory error code (see 
Appendix C). 


NOTE 


Since the completion of a FUNCTN=ASKATT 
request is dependent on outside action 
(operator, hardware) care should be exercised 
in its use (it is possible to give up control and 
never regain it). 


REMOVE and ASKATT functions cannot be chained. 


COMMAND 


This single macro will generate a command word (or 
words)* for a physical input/output operation on 
unit record, magnetic tape, disc or communications** 
devices. Since the macro takes a wide variety of 
possible forms according to the type of device and 
operation for which it is being used, separate 
descriptions are given for each of the different classes 
as reflected in the value of the OPCODE operand. 


* The generated word is not directly executable code and 
must therefore be coded in a data area of the user’s 
program. 

** Details in Telecommunications Reference manual. 
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COMMAND Macro for Basic Data Channel 
(Unit Record Devices and Magnetic Tape} 


This macro generates a command word for physical 
input/output operations on card reader, card punch, 
line printer, magnetic tape, etc. (devices connected to 
the basic data channel). The generated command 
word specifies the hardware operation to be executed 
and, for commands that require data transfer, it 
designates the storage area associated with the 
operation. In addition, various operation modifiers 
may be supplied. 


Name Operation Operand 


[tag] COMMAND OPCODE=X‘nn' 
[BUFADR=symbolic address] 
[BUFSIZ=decimal number] 


[cHain- tne | 
[sizerr- ea 
[skip- (no } | 


OPCODE=X‘nn’ 


This parameter is a two-digit hexadecimal code 
specifying the hardware operation to be performed 
(see Table 7-5), or a command program jump 
command (OPCODE=X’08’). 


BUFADR=symbolic address Optional 
Specifies the address of the data buffer. 


BUFSIZ=decima!l number Optional 


Specifies the length of the data buffer in bytes. The 
maximum allowable value is 65,535 bytes. BUFSIZ=0 
is not valid at execution time. 


YES 
CHAIN= ie Optional 


Indicates that another command word follows 
contiguously. Omission of this operand indicates that 
this is the last (or only) command word in the 
command program. CHAIN=NO represents the 
command word being the last one in the command 
program. 


SIZERR= 


(ve sie Optional 


Any difference between the length of the data record 
processed at the hardware-software interface and the 
size of the data buffer is detected by the I/O routines. 
This “‘incorrect fength indication” is normally treated 
as an error condition and causes termination of a 
command program at that point. The SIZERR=YES 
operand (suppress length check) allows chaining to 
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proceed regardless. SIZERR=NO causes termination 
of a command program at that point. 


Optional 


YES 
SKIP= (No 


SKIP=YES causes suppression of the transfer of data 
into storage during this command word execution. 
SKIP=NO causes the transfer of the data storage. 


COMMAND 
Macro for DCABLE Operation 


Creates a command word for a physical disc 
operation to return the disc drive cable address. When 
an EXCP executes this command word it will read the 
status of the physical device identified in the related 
PCB and will place status indication in a two-byte 
buffer specified by BUFADR. 


Name Operation Operand 
[tag] COMMAND OPCODE=DCABLE 


BUFADR=symbolic address 


[CHAIN= tio t 


OPCODE=DCABLE 
Operation code for returning disc drive cable address. 
BUFADR=symbolic address 


Specifies the two-byte buffer area where the disc 
drive cable address will be returned. 


YES 


NO Optional 


CHAIN= | 


Indicates that another command word _ follows 
contiguously in storage and is to be executed 
immediately after this one. CHAIN=NO represents 
the command word being the last one in the 
command program. 


COMMAND Macro for a DCSEEK Operation 


Creates a command word for a physical disc seek 
operation. When executed by an EXCP, this 
command word will cause a disc seek to the cylinder 
and track specified in a buffer pointed to by 
BUFADR. 


Name Operation Operand 
[tag] COMMAND OPCODE=DCSEEK 
BUFADR=symbolic address 
YES 
[CHAIN= {No }] 


OPCODE=DCSEEK 


Operation code for a disc seek. 


Table 7-5. Peripheral Device Basic Hardware Operation Codes 


Device Operation 


Card Reader (8010) Read sate Feed): ’ 
BCDIC mode 
Card Image mode 


Test I/O 
No Operation 
Sense 


Line Printer (6120, 5060) Write (no line spacing) 


Write and Space 
Space 1 line 
Space 2 lines 
Space 3 lines 
Space 4 lines 


Space 14 fines 
Space 15 lines 


Space Immediate: 
Space 1 line 
Space 2 lines 
Space 3 lines 
Space 4 lines 


Space 14 lines 
Space 15 lines 


Write and Skip: 
Skip to Channel 1 (top of form) 
Skip to Channel 2 
Skip to Channel 3 
Skip to Channel 4 


Skip to Channel 11 
Skip to Channel 12 


Skip Immediate: 
Skip to Channel 1 (top of form) 
Skip to Channel 2 
Skip to Channel! 3 
Skip to Channel 4 


Skip to Channel 11 
Skip to Channel 12 


Test 1/O 
No Operation 
Sense 


*These numbers in the series are being incremented by eight. 


OPCODE 


02 
22 
00 
03 
04 


g9* 
91 
99 
Al 


D9 
E1 


7-25 


Table 7-5. Peripheral Device Basic Hardwara Operation Codes (Continued) 


Operation OPCODE 


Card Reader/Punch (8025) Read Only: ‘ 
EBCDIC mode OA 
Card Image mode 2A 


Feed and Select Stacker: 
without offset 23 
with offset A3 


Read, Feed and Select Stacker: 


EBCDIC mode, without offset 02 
EBCDIC mode, with offset 82 
Card Image mode, without offset 22 
Card Image mode, with offset A2 


Punch, Feed and Select Stacker: 


EBCDIC mode, without offset 01 

EBCDIC mode, with offset 81 

Card Image mode, without offset 21 

Card image made, with offset Al 

Test t/O oo 

No Operation 03 

Sense 04 

Magnetic Tape (3237) Write Forward 01 

Read Forward 02 

Rewind : 07 

Rewind and Unload OF 
Backspace: 

Block 27 


File 2F 


Forward Space: 


Block 37 
File 3F 
Write Tapemark (End-of-File) , 1F 


Erase Gap 17 


Force Error Mode: 


Set E3 

Clear D3 

Test 1/0 00 
X5 

No Operation X6 
XD 

XE 

Sense 04 
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BUFADR=symbolic address 


This specifies the address of a four-byte buffer which 
is assumed to have been preset by the user with the 
cylinder and track numbers to which the seek is to be 
made. The buffer format should be: 


0 7 «#0 7 


FBA Cylinder number 
FBA+2 Track number 
CHAIN= fest Optional 


Indicates that another command word follows 
contiguously in storage and is to be executed 
immediately after this one. This parameter must be 
included to reserve the unit until the subsequent data 
transfer is complete. CHAIN=NO_ represents the 
command word being the last one in the command 
program. 


COMMAND Macro for a DCSRCH Operation 


Creates a command word for a physical disc search 
operation. When executed by an EXCP, this 
command word causes a disc search to be performed. 
The search command allows the user to locate, on the 
current track, the data he wishes to process. This is 
done by analyzing the physical track records for type 
and content, searching for the record specified by 
BUFADR. When the specified record is found, the 
next contiguous command word in the command 
program is executed”. If the search fails to find the 
specified record on the track, the command program 
is discontinued at this point and the abnormal 
completion bit is set in the request block. 


Name Operation Operand 
[tag] COMMAND OPCODE=DCSRCH 


BUFADR=symbolic address 
BUFSIZ=decimal number 


HA 
[FIELD= | RZCNT} | 
RNCNT 


[ cHain= { Meal 
OPCODE=DCSRCH — 


Operation code for a disc search. 


*This will normally be a DCREAD or DCWRIT to read or 
write the actual data record associated with the search. The 
search should always be made for a field (usually a count 
field) preceding the record to be processed. Appendix E 
contains further information on the organization and 
structure of physical disc records. 


BUFADR=symbolic address 


Specifies the address of a buffer containing the data 
to be used in comparing to the field being searched. 
This buffer must begin on a word boundary. 


BUFS!Z=decimal number 


Specifies the length of the field being searched for. 


HA 
FIELD=4 RZCNT Optional 
RNCNT 


Specifies the type of field for which to search. 
HA=home address, RZCNT=count field of record 
zero and RNCNT=count field of record n. If this 
parameter is omitted, HA is assumed. Following is a 
table specifying the field to search in order to read or 
write a desired field. 


To Perform 
this DCREAD 
or DCWRIT 
Operation: 


This DCSRCH 
Operation is 

First Required: 

HA No search required 

Data RNCNT 

Key + Data RNCNT 

Count R(N-1)CNT or HA 


Count + Data R(N-1)CNT or HA 


Count + Key + | R(N-1) CNT or HA 
Data 


Note that, when searching in preparation for a write 
operation, any fields that may be situated between 
the search field and the field to be written must be 
skipped using a DCREAD without transfer. 


Optional 


CHAIN=| a 


NO 


Indicates that another command word follows 
contiguously in storage and is to be executed 
immediately after this one (almost always the case 
with the DCSRCH). CHAIN=NO represents the 
command word being the last one in the command 
program. 
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COMMAND Macro for a DCREAD Operation 


Creates a command word or chained group of 
command words for a physical disc read operation. 
When executed by an EXCP instruction, this 
command word (or group of command words) will 
cause a field (or number of fields) to be copied from 
disc into the specified buffer (or buffers). A 
multi-record data field read may be specified by 
including a BUFSIZ parameter which is a multiple of 
the DATSIZ parameter. However, when this is done, 
no other fields may be read by the same macro. 


Name Operation Operand 
[tag] COMMAND OPCODE=DCREAD 


HABUF=symbolic address, 
HAS!Z=decima!l number 
DATBUF=symbolic address, 
DATS1IZ=decimal number 
KEY BUF=symbolic address, 
KEYSIZ=decimal number 
CNTBUF=symbolic address, 
CNTSIZ=decima!l number 
[BUFSIZ=decimal number] 


[ skiP= (no | ] 


[cHain= {FS} ] 


NO 
[rieuoe (RECNT | 
OPCODE=DCREAD —— 
Operation code for a disc read. 
HABUF=symbolic address Optional 


HASIZ=decimal number 


These two parameters are coded as a pair to indicate 
that a home address field is to be read. HABUF 
specifies the address of the buffer into which the 
home address is to be placed and HASIZ specifies the 
buffer length in bytes. 


DATBUF=symbolic address Optional 
DATSIZ=decimal number 


These two parameters are coded as a pair to indicate 
that a data field is to be read. DATBUF specifies the 
address of the buffer and DATSIZ specifies the length 
of the buffer, except in the case of multi-record reads 
(see BUFSIZ). 


KEYBUF=symbolic address Optional 
KEYSIZ=decimal number 


These two parameters are coded as a pair to indicate 
that a data field is to be read. KEYBUF specifies the 
address of the buffer, and KEYSIZ its length. 
CNTBUF=symbolic address Optional 
CNTSIZ=decimal number 
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These two parameters are coded as a pair to indicate 
that a count field is to be read. CNTBUF specifies the 
address of the buffer, and CNTSIZ its length in bytes. 


BUFSIZ==decimal number Optional 


This parameter is to be coded for multi-record reads 
only. It indicates the overall length of the data buffer 
(DATBUF); it should be a multiple of the value of 
DATSIZ. 


YES 


ional 
NO Optiona 


SKIP= | 


When this parameter is included no data will be 
transferred to memory so that fields may be skipped 
and/or the cyclic burst bytes” of a record may be 
checked. The SKIP=NO option (default) reads data 
into the buffer area. 


Optional 


FIELD= bee 


RNCNT 


This option gives the record in the count field. 
FIELD=RZCNT is record O in the count field; 
FIELD=RNCNT is record n in the count field. 


ot 


NO Optional 


CHAIN= | 


Indicates that another command word follows 
contiguously in storage and is to be executed 
immediately after this one. CHAIN=NO (default) 
represents the command word being the last one in 
the command program. 


The following table illustrates the valid combinations 
of parameters which may be coded in a DCREAD 
macro. (In all cases SKIP=YES may be included to 
suppress data transfer.) 
Multi- 
Record 


Operation Buffer (BUFSIZ) 


Read Home 
Address 


Read Data DATBUF 


Read Key KEYBUF+DATBUF 
and Data 


Read Count CNTBUF 


Read Count CNTBUF+DATBUF 


and Data 


CNTBUF+KEYBUF 
+DATBUF 


Read Count, 
Key and Data 


* Appendix E has further details. 


COMMAND Macro for a DCWRIT or. KEYBUF=symbolic address Optional 


DCFWRIT Operation KEYSIZ=decimal number 

Creates a command word or a chained group of These two parameters are to be coded as a pair to 
command words for a physical disc write operation. indicate that a keyfield is to be written. KEYBUF 
When executed by an EXCP instruction, this specifies the address of the buffer containing the data 
command word (or group of command words) will to be written, and KEYSIZ specifies its length in 
cause data contained in the specified buffer (or bytes. 

buffers) to be transferred to the specified field (or ; 
fields) on disc. ~CNTBUF=symbolic address Optional 


CNTSiZ=decimal number 
Note that with physical write operations to disc it is 


always necessary to specify the length of the variable These two parameters are to be coded as a pair to 
gap which is to be written preceding a count field, or indicate that a count field is to be written. CNTBUF 
the fixed length gap preceding the home address field. specifies the address of the buffer containing the data 
to be written, and CNTSIZ specifies its length in 
Name Operation Operand bytes. Note that whenever a count field is to be 
DCWRIT written its associated variable gap length must be 
[tag] COMMAND = OPCODE= eoccctade calculated: 
HABUF=symbolic address, : : 
HASIZ=decimal number GAP=decimal number Optional 
DATBUF=symbolic address, 
DATS$IZ=decimal number The value of this parameter represents the length in 
KEY BUF=symbolic address, bytes of an inter-field gap. The length of the gap will 
KEYSIZ=decimal number be fixed except when a count field is being written, 
CNTBUF=symbolic address, in which case it must be calculated from the lengths 
ON Tole = secina! number of the preceding key and data fields on the track (see 
[GAP=hexadecimal number] the following table). Appendix D gives the gap 
[ CHAIN= lic }] specifications. : 
[ FIELD= fences de The following table illustrates the decimal number 


values given for the gaps preceding these values. 


DCWRIT : 
opcove-|Ponnr Optional Walire to be 
Operation code for a disc write. OPCODE=DCWRIT : Coded in 
specifies a normal write operation. Operation Buffer GAP Operand 
OPCODE=DCFWRIT specifies a ‘format write’’: this 
is the same as a normal write except that, on Write home 
completion, the rest of the track (up to the index address 
mark) is filled with 1’s (equivalent to a continuous 
gap). Write data DATBUF 
HABUF=symbolic address Optional | Write key KEYBUF+DATBUF 
HASIZ=decimal number and data 


These two parameters are to be coded as a pair to 
indicate that a home address field is to be written. 
HABUF specifies the address of the buffer containing 
the data to be written into the home address, and 


Write Count CNTBUF 


Write count CNTBUF+DATBUF (K+D)x.043 
HASIZ specifies the buffer length in bytes. and data 


DATBUF=symbolic address Optional Write count, CNTBUF+KEYBUF 
DATSIZ=decimal number key and data +DATBUF 


These two parameters are to be coded as a pair to 
indicate that an actual data record is to be written. 
DATBUF specifies the address of the buffer 


containing the data to be written, and DATSIZ K = length of preceding key field 
specifies its length in bytes. D = length of preceding data field 
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Optional 


CHAIN= he 


NO 


Indicates that another command word follows 
contiguously in storage and is to be executed 
immediately after this one. CHAIN=NO represents 
the command word being the last in the command 
program. 


RZONy Optional 


See Vee 


This option gives the record in the count field. 
FIELD=RZCNT is record O in the count field; 
FIELD=RNCNT is record n in the count field. 


COMMAND Macro for a RESTORE 
Operation 


Creates a physical command word which, when 
executed by an EXCP, causes a disc restore operation. 


Name Operation Operand 


[tag] COMMAND OPCODE=RESTORE 


OPCODE=RESTORE 


Operation code for a disc restore. 


COMMAND Macro for a DCJUMP Operation 


Creates a physical command word which, when 
executed by an EXCP, causes the EXCP to next 
execute the command word located at the address 
specified by CWADR. This may be used to link 
command programs. 


Name Operation Operand 
{tag] COMMAND OPCODE=DCJUMP 


CWADR=symbolic address 


CWADR=symbolic address 


Specifies the address of the command word which is 
to be executed immediately following this one. 


CONTROL PROGRAM MACROS 
WAIT — Wait for Service Request Completion 
This macro is used to wait for the completion of one 
or more outstanding service requests. Execution of 


the requesting program will be suspended until 
completion of the specified request(s)". Except for 
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the optional LIST and ERRCOMP, only one other 
operand may be coded with this macro; depending 
upon the particular parameter used, the macro will 
wait for completion of: 


@ any one of the outstanding requests (MODE 
= ANY) 


e all of the outstanding requests (MODE 
ALL) 


e a specific outstanding request (REQADR 
symbolic address) 


U 


Note that when the REQCNT option is used the 
WAIT macro is satisfied on any of the following 
conditions: 


e When the WAIT macro is issued and the 
system detects that no requests are 
outstanding. 


e@ when the WAIT macro is issued and the 
count of outstanding requests is not equal to 
that specified by REQCNT 


e otherwise, when the first of any outstanding 
request operations is completed 


Name Operation Operand 
ean 
[tag] WAIT [Move RL ] 


[REQADR=symbolic address] 


[REQCNT=symbolic address} 


[uist-{VESt 


[enrcom-{ iif] 


Optional 


mope-{ANY | 


ALL 


This operand provides the option of waiting for the 
completion of any one or all of the currently 
outstanding requests. 


REOQADR=symbolic address Optional 


This operand should be used when it is desired to 
wait for the completion of a single specific request. 
The symbolic address must be the address of the first 
word in the request block (parameter list) of the 
specific request to wait for (not service request 
instruction itself). 


REQCNT=symbolic address Optional 


This operand specifies the location of a one-byte field 
containing the hexadecimal count of the number of 
requests known to be outstanding. Use of this 
operand gives a wait for the completion of any service 
request. 


*If none of the specified requests is outstanding at the time 
the WAIT is executed, control will be returned immediately 
to the requesting program. 


Optional 


List| 3) 


NO 


To be used when either the system linkage (service | 


request instruction) or the pararneter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated in line. 


Optional 


ER rcoMP=| \F°| 


NO 


’ 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMP=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


DELAY — Suspend Program Executiont 


This macro causes program execution to be 
suspended for a specified period of time, with the 
option of resuming on completion of any outstanding 
service request. The period of suspension may be 
specified either by the SECONDS operand or by the 
CYCLES operand (one of which is always required). 


Name Operation Operand 


[tag]} DELAY SECONDS=symbolic address 


CYCLES=symbolic address 


[BREAK= od 
sr Qf 


[ERRCOMP= hag 


SECONDS=symbolic address Optional 


Specifies the location of a one-word field containing 
the desired delay in seconds (hexadecimal). 


CYCLES=symbolic address Optional 


Specifies the location (hexadecimal) of a one-word 
field containing the desired delay in cycles (one cycle 
= 50.2 milliseconds). 


“4 


BREAK=YES indicates that program execution is to 
be resumed immediately after any outstanding service 
request is completed. When this operand is omitted or 
BREAK=NO, the program will be resumed only when 
the specified delay time has elapsed. 


BREAK= { Optional 


t Not available on minimal! system. 


YES 


NO Optional 


ust=| 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


Optional 


ER rcom={ ie 


NO 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMPENO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


INFORM — Service Request Completed 


The INFORM macro informs the requesting program 
that one of the program's outstanding service requests 
has been completed. INFORM returns control 
immediately to the user and subsequently indicates 
that a service request has been completed by setting 
the complete bit in the INFORM request block (bit 0 
of the third byte of the parameter list). The REQCNT 
operand points to a location containing a one-word 
count of the number of service requests which are not 
known to have been completed. The purpose of the 
count specification is to indicate whether any of the 
requests whose completion status is unknown have 
already been completed by the time the INFORM 
macro is executed (this will include the possibility of 
a request being completed in the interval between the 
issuance and actual processing of the INFORM). Thus 
the INFORM macro is satisfied by any one of the 
following conditions: 


@ when no service requests are outstanding 


e@ when the number of outstanding requests is 
less than that specified by REQCNT 


@ when the first outstanding request is 
completed 


lf when INFORM is issued, the number of 
outstanding requests exceeds the REQCNT 
specification, an error is assumed and the INFORM 
request is completed as abnormal. 


Name Operation Operand 


[tag] INFORM REQCNT=symbolic address 


[usr¥*}) 


[ ERRCOMP={,6. \ 
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REOCNT=symbolic address 


Specifies the address of a one-byte location 
containing the number of service requests that are not 
known to have completed (outstanding). 


LIST= net Optional 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


Optional 


ERRCOMP-| Xe | 


NO 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMPENO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


POST — Create Compressed Communication Byte 


This macro, in conjunction with RPOST, is used for 
communication between user job steps. POST takes 
the first eight bytes located at INFOADR and 
interprets each byte to modify the corresponding bit 
in a compressed communication byte located in the 
Job Control Table*. At the start of a job the POST 
communication byte is initialized to zero. 


Name Operation Operand 


[tag] POST 
[ uist={¥ES} ] 


[RetuAN={i5 | | 


[ ERRCOMP= Ba a 


INFOADR=symbolic address 


Specifies the location of an eight-byte buffer 
containing the information to be posted. The buffer 
should contain only EBCDIC 0's, 1’s or X’‘s. These 
bytes will be interpreted as follows to modify the 
corresponding eight b/ts in the communication byte: 


EBCDIC 0 = reset bit to 0 
EBCDIC 1 =set bit to 1 
EBCDIC X = leave bit unchanged 


*This scheme is compatible with |BM’s UPSI bit mechanism. 
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INFOADR=symbolic address 


ust={"F5| 


NO Optional 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


aa 


RETURN| ve 


Optional 


To be used when the user program wishes to be given 
control immediately on recognition of the request, 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


Optional 


ER RCOMP=| 6 | 


NO 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMP=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


RPOST — Expand from Communication Byte 


This macro is used to read information, located in an 
interjob step communication area, which was posted 
there either by a POST macro in a previous job step 
or by the SWITCH=parameter in a //SET Control 
Language statement*. Each bit in the one-byte 
communication area is expanded to an EBCDIC 
equivalent and placed in the buffer specified by 
INFOADR. 


Name Operation Operand 
[tag] RPOST INFOADR=symbolic address 


[ List=(\e} ] 


[ RETURN=\ 6 | 1 


[ ERRCOMP= iN: a 


INFOADR=symbolic address 


Specifies the location of an eight-byte buffer where 
the interpreted information will be placed. Each b/t 
in the communication byte will be converted to an 
EBCDIC byte as follows: 


Binary 0 = EBCDIC O 
Binary 1 = EBCDIC 1 


YES 


NO Optional 


ust=| 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


Optional 


RETURN-{ v0 | 


NO 


To be used when the user program wishes to be given 
control immediately on recognition of the request, 
bubefore completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


fe Optional 


ER RCOMP| Ve 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMPE=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


SETCOM — Transfer to Job Control Table 


This macro, in conjunction with GETCOM, is used 
for communication between user job steps. It 
transfers, without modification, eight bytes of 
information located in a user-specified buffer to an 
eight-byte communication area in the Job Control 
Table where it may be picked up by a GETCOM ina 
subsequent job step. At the start of a job the 
communication area is initialized to all blanks. 


Name Operation Operand 


[tag] SETCOM INFOADR=symbolic address 


[uist-{\F° a 


[ReTuRN={VF°} ] 


[errcomp={i5}] 


INFOADR=symbolic address 


Specifies the location of an eight-byte buffer 
containing the data to be transferred to the 
communication area. 


Optional 


List=[6)| 


NO 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated. separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


Optional 


RETURN=| vo) | 


NO 


To be used when the user program wishes to be given 
control immediately on recognition of the request 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


Optional 


ERRCOMP=| V0 | 


NO 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 


ERRCOMPE=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


GETCOM — Transfer from Job Control Table 
Communication Area 


This macro is used to obtain the information which 
had been placed in an eight-byte communication area 
by a SETCOM executed in a previous job step. The 
content of the communication area, located in the 
Job Control Table, is moved, without modification, 
to an eight-byte buffer specified by INFOADR. 


Name Operation Operand 
[tag] GETCOM INFOADR=symbolic address 


[uist-{re° t) 


[RetuRN={VF°}] 


[erRcomp-{*F°}] 


INFOADR=symbolic address 
Specifies the location of an eight-byte user buffer 


into which the contents of the communication area 
will be moved. 
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Optional 


List-(")| 


NO 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


Optional 


RETURN-| ie 


NO 


To be used when the user program wishes to be given 
control immediately on recognition of the request, 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


YES 


NO Optional 


ERRCOMP=| 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMPE=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


ACCEPT — Read //PAR Card 


This macro is used to obtain data contained on //PAR 
cards supplied in the Control Language deck. 
ACCEPT transfers the EBCDIC content of a single 
//PAR card to the buffer specified by DATBUF1. 


The particular //PAR card read by the ACCEPT is 
determined by a pointer located in the Job Control 
Table. At the start of the job step, this pointer is 
initialized to point to the first //PAR card so that the 
first ACCEPT executed in the step will read the first 
//PAR card supplied with this step. Each time an 
ACCEPT is executed the //PAR card pointer is 
updated to the next consecutive card so that on the 
next execution the next //PAR card will be read. 


If, when an ACCEPT is executed, there are no more 
//PAR cards left to be read, control will be 
transferred to the location specified by the ENDADR 
operand. 


The optional operand PARNUM allows the //PAR 
pointer to be set to any desired //PAR card by 
specifying a user location containing a count (since 
the //PAR cards are considered to be numbered 1 
through 7 by implication). Each time an ACCEPT 
macro with a PARNUM specification is executed, the 
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content of the user counter specified by PARNUM 
will be incremented by 1 so that this same ACCEPT 
may be re-executed to read the next //PAR card. 


The format of the data transferred to the buffer 
consists of a four-byte Common Stored Data Format 
(CSDF) control header preceding the data from the 
//PAR card, unless the optional operand CSD=NO is 
included. The content of the //PAR card is always 
stripped of characters through the first blank (so as 
not to include ‘’//PAR”’ itself) and is also stripped of 
the sequence number field (columns 73 through 80) 
unless the optional operand STRIP=NO is included. 


Name Operation Operand 

[tag] ACCEPT DATBUF 1=symbolic address 
[CSD=NO] 
{STRIP=NO] 


[PARNUM=symbolic address] 
ENDADR=symbolic address 


[Lisr-{ "Fs ] 


[ReTuRN-{ "> 7 


[errcomp-| net 


DATBUF 1=symbolic address 


Specifies the location of the buffer into which the 
data from the //PAR card will be transferred. 
CSD=NO (Optional) 
If this operand is used the parameter line will not be 
preceded by the CSDF control header. 
STRIP=NO (Optional) 
If this operand is used the Sequence Number Field 
(card columns 73 through 80) will not be stripped. 
PARNUME=symbolic address (Optional) 
Specifies the location of a one-word binary counter 
whose value is to be used as a //PAR card pointer. A 
value of 1 will cause the first //PAR card to be read, 
and 2 the second, and so on. Each time the ACCEPT 


is executed, the value of the counter will be increased 
by 1. 


ENDADR=symbolic address 


This required operand specifies the program address 
where control is to be transferred if all the //PAR 
cards have been read (value of system’s //PAR 
counter greater than number of //PAR cards 
supplied) or if the PARNUM specified is greater than 
the number of //PAR cards supplied. 


Optional 


usr={YES| 


NO 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


YES 


NO Optional 


RETURN-| 


To be used when the user program wishes to be given 
control immediately on recognition of the request, 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


a 
NO 
To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMPE=NO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


ER RCOMP=| Optional 


DISPLAY — Write Message on SYSOUT 


The DISPLAY macro is used for writing a one-line 
message on the SYSOUT file. The address of the 
message buffer, which must be aligned on a word 
boundary, is specified by DATBUF. The format of 
the buffer must be as follows: 


0 Space for CSDF Control Header 
(4 bytes) 
2 
4 ASA carriage control message byte 1 
character 
6 message byte 2 message byte 3 


| message byte n-1 message byte n | 


The first four bytes of the buffer are reserved for a 
Common Stored Data Format (CSDF) control header 
to be generated by the system. The fifth byte, 
preceding the message, is an ASA carriage control 
character” (not to be printed) and the message itself 
is an EBCDIC character string up to 132 bytes in 
length, starting in the sixth byte. If the message is 
shorter than 132 bytes, a storage location containing 
the length must be set up and the DATSIZ operand 
must be included in the call. 


*Details in Control Program and Data Management Services 
— Basic Reference. 


Name Operation Operand 


[tag] DISPLAY DATBUF=symbolic address 


[DATSIZ=symbolic address] 


_{ YES 
[errcom=| V5 


DATBUF=symbolic address 


Specifies the address of the first byte in the message 
buffer. This will be the address of the space reserved 
for the CSDF control header and the first byte of the 
message itself (the ASA control character) should be 
displaced 4 bytes from this address. 


DATSIZ=symbolic address Optional 


Specifies the address of a one-word location 
containing the length of the message. If this operand 
is omitted, the message length is assumed to be 132 
bytes. 


Optional 


ERRCOMP=| \C | 


NO 


lf ERRCOMP=YES is specified, the program is not 
aborted. When ERRCOMP=NO is coded, or the 
default is taken, the program will be aborted if an 
error occurs. 


MEMLIM — Identify Partition Limit 


This macro returns the first byte address of the 
highest addressable 256-byte page of storage available 
to the problem program in the partition in which the 
program is running. The returned address is expressed 
as the absolute address of the first word of the last 
addressable page. MEMLIM is intended for enabling 
programs which are expected to run in partitions of 
various different sizes to ‘spread themselves out” to 
occupy as much space as is available (in the interest 
of efficiency). In this situation, the partition space 
pool should always be fixed by means of the 
appropriate Linkage Editor directive.” 


Name Operation Operand 


[tag] MEMLIM INFOADR=symbolic address 


fusrY}) 


[ReTURN-{ Aq }] 


[ERRCOmP= ‘ie a 


*Linkage Editor portion of Program Library Services 
Reference. 
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INFOADR=symbolic address 


Specifies the location of a two-byte area where the 
address of the highest addressable 256-byte page is to 
be placed. 


a Optional 


LIsT-|\6 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates the parameter 
table (list) only. When no LIST operand is specified, 
both the service request and the parameter table are 
generated. 


RETURN-{ No | Optional 


To be used when the user program wishes to be given 
control immediately on recognition of the request 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


ER RCOMP=| Optional 


YES 
NO 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMP=NO is coded, or the default is taken, the 
program will be aborted if an irrecoverable error 
occurs. 


SETIF — Post Code for Control Language Test 


This macro enables a program, running as one step of 
a multi-step job, to post in the Job Control Table 
(usually at step completion) a code which may be 
tested by a Control Language //IF statement” in 
order to govern the subsequent course of the job. The 
code to be posted is one byte in length (EBCDIC 
character); its address is specified by INFOADR. 


Name Operation Operand 


[tag] SETIF 


[uist=(YES\] 
[RETURN={h9 }] 


[ERRcomP={ ig" t) 
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INFOADR=symbolic address 


INFOADR=symbolic address 


Specifies the location of the one-byte (EBCDIC 
character) of data to be posted in the IF code field of 
the Job Control Table. 


Optional 


YES 
usr-{Y5| 


To be used when either the system linkage (service 
request instruction) or the parameter table is to be 
generated separately. LIST=NO generates the service 
request only; LIST=YES generates parameter table 
(list) only. When no LIST operand is specified, both 
the service request and the parameter table are 
generated. 


Optional 


RETURN=| 0) | 


NO 


To be used when the user program wishes to be given 
control immediately on recognition of the request 
but before completion (RETURN=YES). When 
RETURN=NO is coded, or the default is taken, 
control will only be returned on completion of the 
request. 


Optional 


ER RCOMP-| vee 


NO 


To be used when the user decides to retain control in 
the event of an error (ERRCOMP=YES). When 
ERRCOMPENO is coded, or the default is taken, the 
program will be aborted if an error occurs. 


HALT — Terminate Program 


The HALT macro is used to perform normal 
termination of a user’s program step. This macro will 
not result in a memory dump unless DUMP=YES has 
been coded in the //EXECUTE statement associated 
with the program. The format for HALT is as 
follows: 


Name Operation Operand 


[tag] HALT 


*See Control Language Services Reference. 


EHALT — Terminate Program 


The EHALT (error halt) macro is used to request 
termination of a user’s job. This macro will not 
automatically give a memory dump _ unless 
DUMP=YES has been coded in the //EXECUTE 
statement associated with the program. The format 
for EHALLT is as follows: 


Name Operation Operand 


[tag] EHALT 


ABEND — Terminate Program Abnormally 


The ABEND macro is used to request abnormal 
termination of a job, and to pass a completion code 
to Job Monitor for display. A dump will be given 
unless DUMP=NO is specified on the //EXECUTE 
statement. The completion code is a 16-bit binary 
value. The format for ABEND is as follows: 


Na me Operation Opera nd 


[tag] ABEND INFOADR=symbolic address 


INFOADR=symbolic address 


Specifies the first byte address of the area containing 
the completion code. 


TIME — Retrieve Time of Day 


The TIME macro returns the current time of day in 
the operand specified. The time of day is returned in 
an unpacked decimal format: hhmmss, where hh is 
the hour, mm is the minute, and ss is the second. The 
format for TIME is as follows: 


Name Operation Operand 


[tag] TIME INFOADR#=symbolic address 


INFOADR=symbolic address 


Specifies the first byte address of the area which 
receives the time. 


SDATE — Retrieve System Data 


The SDATE (system date) macro returns the system 
data in the operand specified. The date is returned in 
one of two unpacked decimal formats: mmddyy or 
yyjij, where mm is the month, dd is the day, yy is the 
year, and jjj is the Julian day. The format for SDATE 
is as follows: 


Name Operation Operand 


tag SDATE INFOADR=symbolic address 


move={—} 


INFOAD R=symbolic address 


Specifies the first byte address of the area that 
receives the data. 


={f 
move=|°| 


Specifies the current date in the calendar (C) 6-byte 
format mmddyy or the Julian (U) 5-byte format 
vyijj. The default value is C. 


JDATE — Retrieve Job Date 


The JDATE (job date) macro returns the date 
provided for by a //SET statement. The date returned 
will be the system date unless the //SET statement 
has specified a job date. The date is. returned in one 
of two unpacked decimal formats: mmddyy or yyjjj, 
where mm is the month, dd is the day, yy is the year, 
and jjj is the Julian day. The format for JDATE is as 
follows: 


Name Operation Operand 
tag JDATE INFOADR=symbolic address 


MODE= {=} 


iINFOADR=symbolic address 


Specifies the first byte address of the area which 
receives the date. 


move=| +] 
J 
Specifies the current date in the calendar (C) 6-byte 


format mmddyy or Julian (J) 5-bit format yyjjj. The 
default value is C. ; 


CONSOLE COMMUNICATION MACROS 


Two macros, CONSOLE (an active macro) and 
MESSAGE (a data macro), are available for 
communicating with the operator’s console. 
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CONSOLE — Transmit Message to Console and 
Optionally Receive Reply 


The: CONSOLE macro enables programs to transmit 
messages to the operator’s console and optionally 
receive replies. The main-storage format of the 
message to be sent to the console must include two 
fields, a control block which is not typed and the text 
field which contains the actual message. The buffer 
set up to receive a reply from the console (if any) 
must contain a control block followed by the actual 
buffer for the reply text. The format of CONSOLE is 
as follows: 


Name Operation Operand 


[tag] CONSOLE DOATBUF1=symbolic 
address 
[DATBUF2=symbolic 
address] 


DATBUF 1=symbolic address 


Specifies the address of the message contro! block 
which is followed by the message test. 


DATBUF2=symbolic address (Optional) 
Specifies the address of the reply control block which 
is followed by the reply buffer area. 


MESSAGE — Set Up Message Format 


The MESSAGE macro, to be used in conjunction 
with the CONSOLE macro, simplifies the generation 
of messages by creating the correct format required 
by CONSOLE. A tag is required for all MESSAGE 
macros so that the corresponding CONSOLE macro 
may locate it. Two formats exist for the MESSAGE 
macro, one for generating an output message and one 
for generating a reply buffer. 


Generation of an Output Message 


The format for generating an output message is as 
follows: 


Name Operation Operand 
tag MESSAGE [DATBUF1=symbolic address] 


DATSIZ1=decimal number 
DATATXT=character string 


[move-{}] 
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DATBUF 1=symbolic address (Optional) 
Enables a name to be attached to the beginning of the 
message text field. 


DATSIZ1=decimal number 


Specifies the decimal length (in bytes) of the message 
text. If no length is specified, the text length will be 
used. If there is no message, a length of zero is 
assumed. The maximum value of DATSIZ1 is 100. 


DATATXT=character string 


Specifies the actual message to be placed in the 
message text field. It is created in EBCDIC and may 
be up to 100 characters (bytes) long. The default is a 
string of blanks, with length being determined by the 
parameter DATSIZ1. The character string must be 
coded in the form, C’message text’. 


MODE= to (Optional) 


Specifies whether the message is informative (1) or 
directive (D). MODE=D indicates that the message 
calls for some operator action. The default value of 
MODE is |. 


Generation of a Reply Buffer 

The format for generating a reply buffer is as follows: 
Name Operation Operand 
tag MESSAGE [DATBUF2=symbolic address] 


DATSIZ2=decima!l number 


DATBUF2=symbolic address (Optional) 
Enables a name to be attached to the beginning of the 
reply text field. 


DATSIZ2=decimal number 


Specifies the decimal length in characters (bytes) of 
the reply buffer to be generated. The reply field will 
be assembled with blanks. The maximum value of 
DATSIZ2 is 100. 


A. PACK CATALOG AND CENTRAL 
CATALOG FORMATS 


The formats used by the pack catalog and central 
catalog of the disc are discussed in the following 
paragraphs. 


PACK CATALOG 


Figures A-1 through A-5 illustrate the use of the 
name, attribute and space elements in generating the 
pack catalog. The normal block of the pack catalog is 
128 bytes, and the continuation element is 64 bytes 
for normal files and 128 bytes for a continuation to 
the description of pack space, which is catalog blocks. 


At disc initialization time, the pack catalog is created 
with block formatting as follows (assuming the pack 
contains the central catalog): 


Block 1 Entry that describes the pack 
catalog itself 


Block 2 Entry that describes the space 
available on the pack 


Block 3 Entry that describes the space 
occupied by the central catalog 


Block 4 First block of space available in 
the pack catalog. Name element 
fields are filled as follows: 


Control bytes X‘8200007C’ 
X’000500’ 
Previous name X‘000000‘ 


Next name 


Block 5-n Remaining blocks of space are 
constructed in the same format as 
block 4 with proper linking 
through the next name and 
previous name fields. 


During the process of allocating a data file, one of the 
available blocks is removed from the string of 
available pack catalog blocks and is linked into the 
chain describing existing files. When space is needed 
for a continuation element, another block is removed 
from the available chain. Half of the block is used for 
a continuation element and the other half is linked to 
start the chain of available continuation space. 


CENTRAL CATALOG 


Figures A-6 through A-8 illustrate the use of the 
name, attribute, and volume elements in constructing 
entries for the central catalog. The normal block size 
of the central catalog is 128 bytes, and the 
continuation element is 64 bytes. 


At disc initialization time, the first block is formatted 
as shown in Figure A-7. Remaining blocks are 
considered available and are linked as those in the 
pack catalog. 
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CONTROL BYTES FOR NAME EL EMENT 


FILE NAME: X’00014B’ 


POINTERS TO ATTRIBUTE ELEMENT, SPACE 
ELEMENT AND AVAILABLE PACK CATALOG 
BLOCKS, AVAILABLE PACK CATALOG 
CONTINUATION ELEMENTS 


33 een 
34 

CONTROL BYTES FOR ATTRIBUTE ELEMENT 
63 ee ee eee 
64 

CONTROL BYTES FOR SPACE ELEMENT 

7 SEGMENTS WITH 
UNUSED BYTES 
AT THE END 

127 


Figure A-1. Block 1 — Pack Catalog Entry in Pack Catalog 


NAME 
ELEMENT 


ATTRIBUTE 
ELEMENT 


SPACE 
ELEMENT 


CONTROL BYTES FOR NAME ELEMENT 


FILE NAME: X’00024B’ 


POINTERS TO SPACE ELEMENT 


22 
CONTROL BYTES FOR SPACE ELEMENT 
14 SEGMENTS WITH 
UNUSED BYTES 
AT THE END 
127 


Figure A-2. Block 2 — Space Entry in Pack Catalog 


NAME 
ELEMENT 


SPACE 
ELEMENT 


CONTROL BYTES FOR NAME ELEMENT 


NAME 
FILE NAME: X‘00034B’ ELEMENT 
POINTERS TO ATTRIBUTE ELEMENT 
AND SPACE ELEMENT 
25 eae os ee 
26 
CONTROL BYTES FOR ATTRIBUTE ELEMENT 
ATTRIBUTE 
ELEMENT 
55 
56 =e Oe 
CONTROL BYTES FOR SPACE ELEMENT 
8 SEGMENTS WITH 
UNUSED BYTES SPACE 
AT THE END ELEMENT 
127 


Figure A-3. Block 3 — Central Catalog Entry in Pack Catalog 


A-4 


CONTROL BYTES FOR NAME ELEMENT 


POINTERS TO ATTRIBUTE ELEMENT, 
SPACE ELEMENT, AND 
ASSOCIATED NAME ELEMENT 


49 ieee 
50 

CONTROL BYTES FOR ATTRIBUTE ELEMENT 
79 
80 

CONTROL BYTES FOR SPACE ELEMENT 

4 SEGMENTS WITH 
UNUSED BYTES 
AT THE END 

127 


Figure A-4. Block 4-n — Normal File Entry in Pack Catalog 


NAME 
ELEMENT 


ATTRIBUTE 
ELEMENT 


SPACE 
ELEMENT 


A-6 


63 


CONTROL BYTES FOR SPACE CONTINUATION 


Figure A-5. Pack Catalog Space Element Continuation 


CONTROL BYTES FOR NAME ELEMENT 


NAME 
FILE NAME: X’00014B’ ELEMENT 
POINTERS TO ATTRIBUTE ELEMENT, VOLUME 
ELEMENT, AVAILABLE CENTRAL CATALOG 
BLOCKS, AND AVAILABLE CENTRAL CATALOG 
CONTINUATION ELEMENTS 
CONTROL BYTES FOR ATTRIBUTE ELEMENT 
ATTRIBUTE 
ELEMENT 
CONTROL BYTES FOR VOLUME ELEMENT 
4 VOLUMES VOLUME 
ELEMENT 


Figure A-6. Block 1 — Central Catalog Entry in Central Catalog 
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CONTROL BYTES FOR NAME ELEMENT 


NAME 
ELEMENT 
POINTERS TO ATTRIBUTE ELEMENT, 
VOLUME ELEMENT, AND 
ASSOCIATED NAME ELEMENT 
49 ee ES 7 en 
50 
CONTROL BYTES FOR ATTRIBUTE ELEMENT 
ATTRIBUTE 
ELEMENT 
79 I ee eel 
80 
CONTROL BYTES FOR VOLUME ELEMENT 
3 VOLUMES VOLUME 
ELEMENT 
127 


Figure A-7. Block 2-n — Normal File Entry in Central Catalog 


A-8 


63 


CONTROL BYTES FOR VOLUME CONTINUATION 


Figure A-8. Central Catalog Volume Element Continuation 


B. SERVICE REQUEST MECHANISM 
AND MACRO EXPANSIONS 


INTRODUCTION 


There are essentially two types of system macro 
instructions: action macros and data macros. Action 
macros, which expand into executable code, may be 
further subdivided into user code macros and service 
request macros. User code macros expand into code 
which is primarily executed within the user’s program 
(except for possible nested service request macros). 
Service request macros, on the other hand, link to 
' system routines for their implementation. 


Examples: 
GET, DISPLAY user code macros 


READ, GETCOM service request macros 
MESSAGE, COMMAND data macros 


Most of the control program and block input/output 
macros are service request macros whereas most of 
the physical input/output macros are data macros. 


- The expansions of all service request macros contain a 
service request machine instruction. 


SERVICE REQUEST INSTRUCTION 


The Service Request instruction (mnemonic SR) is 
the only means by which a user program* may 
communicate with the operating system. In practice, 
however, there is no need for the user to code this 
instruction directly, since it will automatically be 


*This same method is also often employed by system 
programs to communicate with each other. 


generated in the expansion of a service request macro 
instruction. Figure B-1 illustrates the control path 
between a user program and operating system. 


SERVICE REQUEST MACRO EXPANSION 
CONVENTIONS 


The expansions of all* service request macros will 
normally begin with the following standard three 
words (with no LIST operand used): 


Service Request Instruction 


Function Code 


Return Information 


Any additional words in the expansion are uniquely 
defined for each macro. 


SERVICE REQUEST INSTRUCTION (BYTES 0 
AND 1) 


This instruction establishes the link with the 
operating system; it is defined as follows. 


* Except for the physical input/output macro, EXCP. 
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SYSTEM 


USER 
PROGRAM 


OPERATING 
SYSTEM 
CONTROL PROGRAM 


RETURN 


SERVICE 
PROGRAM 


PARAMETERS 


Figure B-1. Service Request Linkage to System 


B-2 


Byte.0O Byte 1 


Service Request Function Code: SR = X'13’ 
I: parameter list location indicator 
O immediately following this instruction 


1 at location whose address is contained in 
register 6 


R: Return indicator 
O return control only after request is completed 
1 return control immediately after request is 
accepted 
EP: User error processing indicator 


QO user program to be aborted on occurrence of 
an error 


1 user to retain control after an error 
Request Class: Major class of service request 

O = Debug Request (system only) 

1 = Restricted Request (system only) 
= Control Program Request 
= Block Input/Output Request 
illegal 
= Supervisor Request 


= Telecommunications Request 


~n Oo OFF 8B WN 
Wl 


= Physical Input/Output Request 


FUNCTION CODE (BYTE 2) 


Function or operation code for this request (see 
individual expansions). 


LENGTH (BYTE 3) 


Number of words in this request block, excluding the 
service request instruction (see individual 
expansions). 


RETURN INFORMATION (BYTES 4 AND 5) 


This word is an area where the system will return 
information developed during the execution of the 
request. On initial receipt of the request the whole 
word will be set to zero. The return information field 
is defined as follows: 


Byte 4 Byte 5 
ee 
01 2 3 7 O 7 


BEES Not Used Return Code | 


Complete Bit (C) 
This bit will be set by the system to indicate that the 
request has been completed (normally or otherwise). 


Error Flag (E) 


When this bit is set an abnormal completion is 
indicated in which case the remainder of the word 
will contain information connected with the error. If 
the error flag is not set, no further information will 
be contained in this word (except in the case of 
END). This bit may be set on completion even if the 
EP bit is not set in the SR. 


End Flag (END) 


When set, this bit indicates that one of a number of 
possible end conditions has been detected. The 
particular end condition is specified by the return 
code in byte 5, as follows: 


00 = Disc EOA (end of allocation) 
01 = Printer Channel 12 

02 = Disc EOF (end of file) 

03. = Card Reader EOF 

04 = Printer Channel 9 

05 = Printer Channels 9 and 12 


Return Code 


This eight-bit code contains specific information 
about the error (return code, Table C-1, Appendix C). 


OPTIONAL PARAMETERS 


Three keyword parameters are usable by most block 
1/O level service request macros: RETURN, 
ERRCOMP, and LIST. The LIST parameter gives the 
option of separating the parameter packet and service 
request instruction, or not doing so. 


lf LIST=YES, the RETURN and ERRCOMP 
parameters cannot be used; if LIST=NO, the 
RETURN and ERRCOMP parameters are the only 
other parameters which can be used. However, if 
LIST is omitted, these two parameters can be used 
independently. 


LIST 


If LIST=YES, only the appropriate parameter packet 
is generated. The LIST=YES option allows the 
generation of the macro parameter packet only once 
in the program. 


If LIST=NO, only a 2-byte standard service request 
instruction is generated. The user must load into 
general-purpose register 6 (R6) the address of the 
parameter packet to be referenced and into register 7 
(R7) the address of the save area address prior to 
issuing the LIST=NO option. 


The 2-byte service request instruction has the 


following format, where O5 defines the Data 
Management expansions and 13 the function code. 


Example: 


OPERATION OPERAND 
1234 tO 11 12.13 14 15 16 17] 18] 19 20 21, 22 23 26 25 26 27 28 29 30 31 32 33 34 35 36 37 38 30 40 41 42 434 
f ee have : 


BUF RENSKPS, . rar 5d ene 
[bere FER. OTY PS “85, Eth od 
~ HEL ate. s., vsSseaszt 7 0! 


With the LODD instruction, the user loads into R6 
the address of a parameter packet which has been 
specified elsewhere in the program (7AG 5), and the 
save area address (SAVE/T) into R7. 


With the’ OPEN macro and a LIST=NO parameter 
specified, only the 2-byte executive request code is 
generated. 


At TAG 5, the OPEN parameter list is generated. 


If the LIST option is omitted, the service request 
instruction is generated followed by the appropriate 
parameter list. The user must load the address of the 
save area into R7 prior to issuing the call. 


OPEN 
Parameter 
Packet 


OPERAND 


af 19 20 21 22.23 24 25 26 27 28 79 30 31 32 33 94 35 36 37 38 39 40.4) 42 434 
Savi RO. 
GB... OPEN . |. D MISFIT LERS. 

Ao: ane? BU.EADR«HSKP.. Daath ate, Oem 
107 Y¥P* 8, USA ee: ee ee a eas de 


a a ee ee ee ee Oo Se ee ee Sa 


The LIST default for the OPEN request results in the 
generation of the service request instruction followed 
by the OPEN parameter packet. 


RETURN 


The RETURN parameter enables the user to request 
that control be returned to his program immediately 
after the service request has been received and 
recognized by the system (but before the function it 
requests has been completed). By coding 
RETURN=YES, the user may save time by 
proceeding with his own processing while the system 
is processing the service request. When 
RETURN=YES is used, detection of request 
completion becomes a user responsibility (he must 
check the complete bit in the return information 
word of the request parameter list). The RETURN 
parameter is mostly applicable to input/output 
service requests, which are relatively slow to 
complete. The default specification, RETURN=NO 
may be coded explicitly if desired. (Note that there 
are certain service request macros on which the 
RETURN parameter is not available.) 


ERRCOMP 


The ERRCOMP parameter allows the user to retain 
control when an error occurs which the system was 
unable to correct. By coding ERRCOMP=YES the 
user has the option of attempting to correct any 
errors or of simply ignoring” them and continuing. 
The default condition ERRCOMP=NO, which may be 
coded explicitly if desired, results in a program abort 
in the event of an error (which the system was unable 
to correct). 


STANDARD SYSTEM SUFFIXES 


lf the programmer wishes to reference a particular 
word of a parameter packet, he may do so by adding 
the standard system suffix to his tag name (name 
symbol). If the tag name is six characters or less, the 
standard suffix is appended to the tag name. If the 
tag name is seven or eight characters, this (these) last 
character(s) is (are) truncated and the standard suffix 
is appended. For this reason the first six characters 
must be unique. The standard suffixes are listed 
alongside the macro expansion with the suffix across 
from the appropriate parameter packet word. 


*Occasionally, a condition may arise which is classified by 
the system as an error but which does not affect the 
outcome of the user program. 


For an example: if the programmer wishes to 
reference the word containing the file type of the 
ALLOC macro, it is located in byte 5 which is 
referenced by the F1 suffix. If his tag name is JOB65, 
the word may be referenced with JOB65F1. 
However, if his tag name is MYJOB658, the reference 
is MYJOB6F 1. 


EXPANSION TABLES 


The expansion of each macro is detailed in the 
following pages; generally there is a map of the bytes 
as stored, followed by detailed assignments of bytes 
and bits. 


The macros are listed in these groupings: 


e Data Management 


ALLOCATE 
EXPAND 
PURGE 
OPEN 
CLOSE 
CLOVE 
LABRTN 


e Block I/O 


STATUS/TYPE 
CONTRL/POSITN 
READ/WRITE 
RESET 


@ Physical 1/O 


EXCP 
PCB 
COMMAND (various applications) 


e@ Control Program 


WAIT 
POST/RPOST 
SETCOM/GETCOM 
ACCEPT 
DISPLAY 
MEMLIM 
INFORM 
SETIF 
DELAY 
HALT 
EHALT 
ABEND 

TIME 

SDATE 
JDATE 


e Console Communications 


CONSOLE 


‘These expansion explanations show the parameter 


tables or lists without the service request instruction 
(for those macros including a service request). Byte 
displacement shown at the side of the tables is 
without the service request; considering the service 
request, it is necessary to increase the displacement 
count by 2. 


Where applicable, bytes containing Segment Tags are 
shown. This tag is mandatory in systems having more 
than 64K bytes of storage, and may be implemented 
in smaller systems. A programmer should be aware 
that the showing of Segment Tags in these format 
drawings does not necessarily imply that the tags will 
be in the system he is using. 
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Table B-1. ALLOCATE Parameter Packet Format Suffixtt 


0 Request Code Length FL 


2 Return Information Return Code CR 
5 


; Data Block Count BC 

10 
12 — Data Block Size BS 
14 Data Record Size RS 
16 S TAG LAB1 
18 LAB1 ADR L1 
20 S TAG LAB2 
22 LAB2 ADR L2 
24 S TAG IDENT 

t 26 IDENT ADR IA 
28 DC Index Block Size IB 
30 index Key Size lK 
32 —— Data Cylinder Number pc 
34 Oo Index Cylinder Number Ic 
36 Spread Factor SF 


Description 


Request code, 1 designates ALLOCATE. 


Length, number of words in the parameter packet (10 to. 19 words) 


Request complete indicator (C) 
(¢] Service request in process 


1 Request complete 


Return information 


i ee ENS SES 


Return code 


Paired file (PF). PF=1 for paired file. 


t Bytes 6 and 7 reflect which optional parameters are present. If a parameter is not present, as evidenced by the presence of a 
zero in that parameter bit, the corresponding 2-byte word in bytes 16 through 37 is omitted, and those parameters that follow 
are telescoped upward by one word. Four-byte parameters such as IDENT ADR with its segment tag and reserved byte, is 
represented by two bits in the pattern. Both bits (IA) must be set if IDENT ADR is present. 


tt The 2-character suffix for unique file identifier. 
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Table B-1. ALLOCATE Parameter Packet Format (Continued) 


Byte Bit Description 
1 Uncataloged (UC). UC=1 for not recording file in the central catalog. 
2 Contiguous space (CS). CS=1 for contiguous space on each volume. 
Cylinder boundary (CB). CB=1 for space segments starting on cylinder boundary. 
4 Write verify (WV). WV=1 for write verification of files.. 


5 Common stored data format (CD). CD=1 for common stored data format. 


3,4 File type (FT) 
00 Permanent 
01 Scratch 
10 Temporary 
11 Work 

File organization (FO) 

000 General 
001 Indexed 
010 _ Relative 
100 Sequential 


LAB1 ADR specified (L1=1)t 


LAB2 ADR specified (L2=1)t 


IDENT ADR specified (IA=1)t 

Index block size specified (1B=1) 

Index key size specified (1K=1) 

Data cylinder number specified (DC=1) 

Index cylinder number specified (IC=1) 

Spread factor specified (SF=1) 

Data block count, number of blocks for data file 


Data block size, size (in bytes) of data block 


= 
XN 
= 
[é) 


Data record size, size (in bytes) of record 
17* Segment tag for L AB1 ADR (S TAG LAB1) 


LAB1 ADR, address of label information for the primary data file LABDEF1, required if IDENT ADR is not 
specified. 


*Optional parameter. 


tTwo fields are shown on format expansion to accommodate paired files. 
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Byte 
21* 


22,23* 


N 
ol 
* 


26,27* 


8 
@ 
* 


32,33* 


f 
G w 
~“ ai 
* * 


*Optional parameter 
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Table B-1. ALLOCATE Parameter Packet Format (Continued) 


Description 
Segment tag for LAB2 ADR (S TAG LAB2) 


LAB2 ADR, address of label information for a paired file LABDEF2. 


Segment tag for IDENT ADR (S TAG IDENT) 


IDENT ADR, address of file identifier as used by Control Language to identify volumes for use in allocation 


Index block size, size (in bytes) of index file 

Index key size, size (in bytes) of key 

Data cylinder number, cylinder number at which allocation of the data file starts 
Index cylinder number, cylinder number at which allocation of index file starts 


Spread factor, physical record interlace to be used in an indexed data file 


Table B-2. EXPAND Parameter Packet Format Suffixtt 


Request Code FL 
CR 
Fl 


Data Block Count BC 


S TAG LAB1 
LAB1 ADR L1 


S TAG IDENT 
IDENT ADR IA 


Description 
Request code, 2 designates EXPND 
Length, number of words in parameter packet (7 to 9 words) 


Request complete indicator (C) 
0 Service request in process 


1 Request complete 

Return information 

Return code 

Paired file (PF), PF=1 for paired file 

Uncataloged (UC), UC=1 for uncataloged file 

Contiguous Space (CS), CS=1 if space on each volume is to remain contiguous. 
LAB1 ADR specified (L1=1)t 


IDENT ADR specified (LA=1)t 


Data block count, number of data blocks to add to the file 


t Byte 5 reflects which optional parameters are present. If a parameter is not present, the corresponding 4-byte field in bytes 10 
through 17 is deleted from the parameter packet and the subsequent parameter words are moved upward. The 4-byte field is 


represented by two bits in byte 5; both bits must be set (or cleared) to reflect the presence of the field. 


tt The 2-character suffix for unique file identifier. 
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Table B-2. EXPAND Parameter Packet Format (Continued) 


Description 
Segment tag for LAB1 ADR (S TAG LAB1) 


LAB1 ADR, address of labe! information for the file. This parameter is required if IDENT ADR is not specified. 


Segment tag for IDENT ADR (S TAG IDENT) 


IDENT ADR, address of file identifier as used by Control Language. This parameter is required if the file is open 
at the time of expansion. 


*Optional parameter 


Table B-3. PURGE Parameter Packet Format 


Request Code 


Return Information 


LAB1 ADR 


IDENT ADR 


Description 


Request code, 3 designates PURGE 
Length, number of words in parameter packet (5 to 7 words) 


Request complete indicator (C) 
0 Service request in process 


1 Request complete 

Return information 

Return code 

Paired file (PF), PF=1 for paired files 
Uncataloged (UC}, UC=1 for uncataloged file 
LAB1 ADR specified (L1=1) 


IDENT ADR specified (IA=1) 


Segment tag for LAB1 ADR (S TAG LAB1) 


Segment tag for IDENT ADR 


t Byte 5 reflects which optional parameters are present. If a parameter is not present, the corresponding 4-byte field in bytes 6 
through 13 is deleted from the parameter packet and the subsequent parameter words are moved upward. The 4-byte field is 


IDENT ADR, address of file identifier as used by Control Language 


Return Code 


S TAG LABi1 


S TAG IDENT 


represented by two bits in byte 5. Both bits must be set to reflect the presence of the field. 


* Optional parameter. 


tt The 2-character suffix for unique file identifier. 


LAB1 ADR, address of label information for data file. This parameter is required if IDENT ADR is not specified. 
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Table B-4. OPEN Parameter Packet Format 


Request Code Length 


Return Information Return Code 


S TAG IDENT 


S TAG LAB ADR 


S TAG BUF ADR 


BUF ADR 


Description 


Request code, 4 designates OPEN 


Request completion indicator (C) 
0 Service request in process 


1 Request complete 


Return information 


Return code 


Control character (CC) 
0 ANSI control characters 


1 Device control characters 


Buffer address (BA) 
0 No buffer 


1 Buffer present 


Type of I/O (T) 

00 Logical 
o1 Block 
10 Physical 


Suffixtt 


FL 


CR 


LB 


BF 


t Byte 4 reflects which optional parameters are present. If a parameter is not present, the corresponding 2-byte word in bytes 8 


through 15 is deleted from the parameter packet and the subsequent parameter words are moved. 


Tt The 2-character suffix for unique file identifier. 


*Optional parameter. 


Table B-4. OPEN Parameter Packet Format (Continued) 


Description 

Usage (U) 

00 Input 

01 Update 

10 Output 
Rewind (R) 

0 No rewind 

1 Rewind 
Label (L) 

0 No label 

1 Label address 


Segment tag for BDT or IDENT (S TAG IDENT) 
BDT or IDENT, address of BDT or address of file identifier 
Segment tag for LAB ADR (S TAG LAB ADR) 


LAB ADR, label address 


Segment tag for BUF ADR (S TAG BUF ADR) 


BUF ADR, buffer address 
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Table B-5. CLOSE Parameter Packet Format 


Request Code Length 


Return Information Return Code 
S TAG IDENT 


BDT or IDENT 


Description 


Request code, 5 designates CLOSE 


Length, number of words in parameter packet (4 words) 


Request complete indicator (C) 
(¢] Service request in process 


1 Request complete 


Return information 
Return code 


Lock (L) 
0 No lock 
1 Lock 


Type of 1/O (T) 

00 Logical 1/O 
01 Block I/O 
10 Physical 1/0 


Rewind (R) 
0 No rewind 


1 Rewind 
Segment tag for IDENT or BDT (S TAG IDENT) 


BDT or IDENT, address of BDT or address of file identifier 


tThe 2-character suffix for unique file identifier. 


Suffixt 


FL 
CR 
BT 


1D 


Table B-6. CLOVE Parameter Packet Format ; Suffixt 


Request Code FL 


Return Information Return Code CR 
S TAG IDENT 


BDT or IDENT 


Description 
Request code, 6 designates CLOVE 
Length, number of words in parameter packet (4 words) 
Request complete indicator (C) 
0 Service request in process 
1 Request complete 
Return information 
Return code ; 
Type of 1/0 (T) 
00 Logical 1/O 
01 Block 1/O 
Segment tag for BDT or IDENT (S TAG IDENT) 
BDT or IDENT, address of BDT or address of file identifier 


tThe 2-character suffix for unique file identifier. 
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Request Code 


2 Le Return Information 


Table B-7. LABRTN Parameter Packet Forrnat 


ELEM 


IDENT ADR 


Byte Bit 


1-7 


de 
N 


> 
“I 


BUFF ADDRESS 


Request code, 7 designates LABRTN 


Return Code 


S TAG IDENT 


S TAG BUFF 


Description 


Length, number of words in parameter packet (6 words) 


Request completion indicator (C) 
0 Service request in process 


1 Request complete 


Return information 


Return code 


Element field (ELEM) 


000 Name element returned 
001 Attribute element returned 
010 Both elements returned 


Segment tag for IDENT (S TAG IDENT) 


IDENT ADR, address of file identifier 


Segment tag for buffer address (S TAG BUFF) 


Address of buffer containing status information 


tThe 2-character suffix for unique file identifier. 


B-16 


Suffixt 


FL 


CR 


Table B-8. STATUS and TYPE Macros Parameter Packet Format Suffix* 


Request Code | Length FL 


CR 

Pointer to File Identifier ; ID 
Buffer pores BA 
Pointer to Byte Counter BS 


Description 

Request Code: STATUS=40, TYPE=41) 

Length, number of words in parameter: 08 

Return Information 

Not used 

Segment Tag 

Pointer to file ID: Address of 8-byte file identifier 

Not used 

Segment Tag 

Buffer Address: first byte address of user-specified buffer area 
Not used 

Segment Tag 


Pointer to Byte Count: address of 2-byte area containing byte count (length of buffer) . 


*The 2-character suffix for the unique file identifier. 
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Table B-9. CNTRL/POSITN Macros Parameter Packet Format Suffix* 


4) Request Code | Length FL 


2 Return Information CR 
4 Sub-Function Code STAG SF 
6 Pointer to File 1D iD 
S$ TAG 
10 Pointer to Block Number BN 
12 Residual Byte Count RC 
es Description 


Request Code: CNTRL=03,POSITN=04 


Length, number of words in the parameter packet, 07 


Return Information 


Sub-Function Code (the indicated bits are set for the function): 


Select Stacker 

Space L.ine Printer 

Skip Line Printer Form 
Rewind (000) 

Rewind and Unload (001) 
Erase gap (010) 

Backspace Record (100) 
Forward space a record (110) 
Forward space a file (111) 
Backspace a file (101) 

Write End-of-File mark (011) 
The vaiue of nn when SS, SK, or SP is used 
Beginning of volume 

End of Volume 

SEEK on position 


Segment Tag 


Pointer to File ID: address of 8-byte file identifier in FDT 


Not used 


Segment Tag 


Pointer to Block No.: address of 4-byte block number (applies to POSITN) 
Residual Byte Count: difference between number of bytes requested and number of bytes received. 


*The 2-character suffix for unique file identifier. 
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Table B-10. READ/WRITE Macros Parameter Packet Format 


Request Code | Length 


Return Information 


Sub-Function Code S TAG 


Pointer to File ID 


Pointer to Block Number 


Residual Byte Count 
Buffer Address 


Pointer to Byte Count 


Description 
Function Code: READ=02, WRITE=01 
Length, number of words in the parameter packet: 11 


Return Information 


Sub-Function Code (the indicated bits are set for the function): 


Select Stacker 

Space Line Printer 

Skip Line Printer Form 

EBCDIC=NO 

The value of nn when SK or SP is used 
The value of nn when SS is used 
Segment Tag 


Pointer to File ID: address of 8-byte file identifier 


Not used 


Segment Tag 


Not used 


Segment Tag 


*The 2-character suffix for unique file identifier. 


Pointer to Block No.: address of 4-byte area containing block number 


Suffix* 


FL 
CR 
SF 


iD 


BN 


RC 


BA 


BS 


Residual Byte Count: difference between number of requested bytes and number of bytes transferred 
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Table B-10. READ/WRITE Macros Parameter Packet Format (Continued) 


Description 


Buffer Address: first byte address of user specified buffer area 


Not used 


Segment Tag 


Pointer to Byte Count: address of 2-byte area containing the byte count (length of buffer) 


Table B-11. RESET Macro Parameter Packet Format Suffix * 


Request Code 


| Length FL 


2 Return Information CR 
4t STAG 
6 Pointer to File ID ID 


Description 


Function Code: RESET=31 


Length, number of words in the parameter packet: 04 


Return Information 


Not used 


Segment Tag 


Pointer to File 1D: address of 8-byte file identifier 


*The 2-character suffix for unique file identifier. 
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Table B-12. EXCP Macro Expansion 


The expansion of the EXCP macro does not include a parameter table (LIST=NO is implied) but it may, depending 
on the operands coded in the call, contain executable code for request setup purposes: 


No operands: SR 

PCB=@register number: MOVR Rn,6 
SR 

PCB=symbolic address: LOD symbolic address,6 
SR 

CP=@register number: STO 6(6),Rn 
SR 

CP=symbolic address: MOVM symbolic address, 6(6) 
SR 

UNORD=symbolic address: MOVB symbolic address, 0(6) 
SR 

UNORD=@register number! STOB 0(6),Rn 
SR 
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Table B-13. PCB Macro Parameter Packet Format 


Unit Ordinal | Length 


Return Information 


Pointer to CP or FC 


8 Pointer to Current CW 
10 Status 
12 Residual Byte Count 
14 Sense 
Pe SN Sp te a a ee A rs = 
16 | Sense | 


*This macro does not use the standard service request prefix. 


Description 


Unit Ordinal: Device identifier 


Length, number of words in this block excluding Device Ident field 


Return Information (same as for service request macros) 


Error Recovery Flag (ERP) 
QO = Call system error recovery when an error occurs 


= Bypass error recovery 


Not used 


Command Program Flag 
10) 
1 


Next word is address of command program to be executed 


Next word is function code to be executed | 


Not used 


Not used 


Pointer to CP or FC 


If CP=0, pointer to command program 


If CP=1, pointer to function code 


Pointer to Current CW: Address of command word being executed 


Status indication 
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Table B-13. PCB Macro Parameter Packet Format (Continued) 


Description 


Residual Byte Count: difference between number of bytes requested and number of bytes transferred 


Sense bytes: variable number of sense bytes depending on device 
Disc = none 

Unit Record = 2 

Mag Tape = 6 


Table B-14. COMMAND Macro Parameter Packet Format (Basic Data Channel) 


Command Code 


Byte Count 


Buffer Address 


*This macro does not use the standard service request prefix. 


Description 
Chain Flag (C) 

0 = No CW follows this one 

1 = Another CW foliows 


Suppress Length Check (SL): if it is set, the CP will not be terminated when the transferred 
byte count differs from the specified byte count. Not used when C = 0. 


Skip (SK): If it is set, data will not be transferred to memory on a data input operation. 

Not used 
Command Code: The eight-bit hardware command code (OPCODE). 

Byte Count: The length of the data buffer (BUFSIZ) in hexadecimal; length must be non-zero 
Not used 
Segment Tag 


Buffer Address: the FBA address of the data buffer (BUFADR). 
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Table B-15. COMMAND Macro Parameter Packet Format (DCABLE) 


S TAG 


6 Buffer Address 


*This macro does not use the standard service request prefix. 


Description 


Chain Flag 
0 = No CW follows this one 
1 = Another CW follows 


Not used 


Command Code: DCABLE=21 


Byte Count: DCABLE=0002 


Not used 


Segment Tag 


Buffer Address: address of buffer into which the disc drive cable address is to be transferred. 
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Table B-16. COMMAND Macro Parameter Packet Format (DCSEEK) 


Buffer Address 


*This macro does not use the standard service request prefix. 


Description 


Chain Flag 
0 = No CW follows this one 
1 = Another CW follows 
Not used 
Command Code: DCSEEK=20 
Byte Count: DCSEEK=0004 
Not used 


Segment Tag 


Buffer Address: address of buffer containing cylinder and track numbers. 
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Table B-17. COMMAND Macro Parameter Packet Format (DCSRCH) 


Byte Count 


S$ TAG 


Buffer Address 


*This macro does not use the standard service request prefix. 


Description 


Chain Flag 

0 = No CW follows this one 
1 = Another CW follows 
Bit Ring Sync: least-significant three bits of Bit Ring Sync Code 
101 = home address fieid 
011 = RO count field 
110 = RN count field 


Gommand Code: DCSRCH=08 


Byte Count: Length of field for which search is being made 
BC = 0005 for home address 
BC = 0009 for count field 


Not used 


Segment Tag 


Buffer Address: address of buffer containing field data for which search is being made 
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Table B-18. COMMAND Macro Parameter Packet Format (DCREAD) 


(1) Read with Transfer 


2 
Buffer Address 
8 Overall Byte Count 
Pee cg es ee ell 
*This macro does not use the standard service request prefix. 
Byte Bit Description 
0 10] Chain Flag 
0 = No CW follows this one 
1 = Another CW follows 
1-3 Bit Ring Sync: least-significant three bits of the Bit Ring Sync code: 
001 = data field 
010 = key field 
011 = Ro count field 
110 = R,, count field 
101 = home address field 
100 = contro! storage data 
4-6 Not used 
7 Repeat Flag 
0 = Execute read command once 
1 = repeat read command until overall byte count is satisfied 
1 0-7 Cornmand Code: READ WITH TRANSFER = 02 
2,3 0-7 Single Record Byte Count: number of bytes to be transferred in each execution of the read 
command, If R=O this will be the total number of bytes transferred. 
4 0-7 Not used 
5 0-7 Segment Tag 
6,7 0-7 Buffer Address: address of the buffer into which the data is to be placed. 
8,9 0-7 Overall Byte Count: total number of bytes to be transferred. Only present when R=1 for a 


multi-record read. 


(2) Read Without Transfer 


2 Byte Count 


Command Code = 04 (Bits 0-7 of byte 1) 
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Table B-19. COMMAND Macro Parameter Packet Format (DCWRIT and DCFWRIT) 


Command Code 


<8 Byte Count 
Gap Length | 


Buffer Address 


Description 


Chain Flag 
0 = No CW follows this one 
1 = Another CW follows 


Bit Ring Sync: least-significant three bits of the Bit Ring Sync Code 
001 = Data field 
010 = Key field 
011 = Rg count field 
110 = R,, count field 
101 = Home address field 
100 = Control Storage data 


Not used 


Command Code 
01 = Write 
10 = Format Write 


Byte Count: number of bytes of data to be written (length of buffers). 
Gap Length: one’s complement of the length of the gap to be written preceding the field 
itself, 


Segment Tag 


Buffer Address: address of the buffer containing the data to be written 


Table B-20. COMMAND Macro Parameter Packet Format (RESTORE) 


*This macro does not use the standard service request prefix. 


Description 
Chain Flag 
0 = No CW follows this one 
1 = Another CW follows 
Not used 


Command Code: RESTORE = 22 


Not used 


Tabie B-21. COMMAND Macro Parameter Packet Format (DCJUMP) 


Address of Next CW 


*This macro does not use the standard service request prefix. 


Description 


Chain Flag 
0 = No CW follows this one 
1 = Another CW follows 
Not used 
Command Code: DCJUMP = 28 
Not used 


Segment Tag 


Next CW Address: locations of the CW to be executed following this one 
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Table B-22. WAIT Macro Parameter Packet Format Suffix* 


0 Request Code | Length FL 

2 Return Information CR 

4 c L | A | S$ TAG BT 

6 Request Block Address (Optionel) BF 
Description 


eeenepnssinp anette anita eens Art RL RAN 


Request Code: WAIT=03 


Length, number of words in the parameter packet: 3 or 4 


Return Information 


Not used 


tn Ae NN ENA sent ntte— renee tenors 


recs fn erent tt A RS 


Not used 


Wait - all flag (L) 


L=1 means wait for all outstanding requests. When L=0 and A=0, wait is 


for specific request. 


Wait - any flag (A) 
A=1 means wait is for any outstanding request. 


an a A LS 


Segment Tag 


Request Block Address: address of request block for wait-specific. Only present when 
L=0 and A=0. 


*The 2-character suffix for unique file identifier. 
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Table B-23. POST/RPOST Macros Parameter Packet Format Suffix* 


) FL 
2 CR 
4 

6 eee Buffer Address IN 


Description 
Request Code: POST=43,RPOST=44 
Length, number of words in the parameter packet: 04 
Return Information 
Not used 


Segment Tag 


Buffer Address: address of an 8-byte buffer. This will either contain the information to be 
posted (POST) or will receive the interpreted information from the system (RPOST). 


*The 2-character suffix for unique file identifier. 


Table B-24. SETCOM/GETCOM Macros Parameter Packet Format Suffix* 
) Request Code | Length FL 
2: Return Information CR 
4 
6 Buffer Address IN 


Description 
Request Code: SETCOM=47,GETCOM=48 
Length, number of words in the parameter packet: 04 
Return Information 
Not. used 
Segment Tag 


Buffer Address: address of an 8-byte buffer. This will either contain the information to be 
transferred (SETCOM) or will receive information from the system (GETCOM). 


*The 2-character suffix for unique file identifier. 
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Table B-25. ACCEPT Macro Parameter Packet Format Suffix* * 


Oo} Request Code | Length FL 


2 Return Information CR 
I N | BS) | H | —_ S TAG BT 
6 Buffer Address eee BF 
: So STAG 
10 End Address EN 
S$ TAG 
a ota Oa ee) at ee a Number Address (Optional) Sesto IN 


Description 


Request Code: 13 


Length, number of words in the parameter packet: 6 or 8 


Return Information 


Not used 


Number Flag 
O= number not specified (current value of //PAR card pointer will be used) 
4 = //PAR card number is specified in word at displacement 16 


Strip Flag 
0 = do not strip sequence number field (card cols 73-80) 
1 = strip sequence number field 


Control Header Flag 
0 = do not include CSDF control header 
1 = include CSDF header 


Segment Tag 


Buffer Address: address of buffer into which data from //PAR card is to be transferred. 


Not used 


Segment Tag 


End Address: address to which program control wil! be transferred when all //PAR cards 
have been read. 


Not used (optional) 


Segment Tag (optional) 


Number Address (optional): address of one-word location containing the //PAR card number 


*Last four bytes will only be present when number flag (N) = 1. 


**The 2-character suffix for unique file identifier. 
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Table B-26. MEMLIM Macro Parameter Packet Format Suffix* 


Request Codie | Length FL 


0 
2 Return Information CR 
4 
6 Buffer Address IN 
Description 

Request Code: MEMLIM=46 

Length, number of words in the parameter packet: 04 

Return Information 

Not used 

Segment Tag 

Buffer Address: Address of buffer into which last page address is to be placed. 
*The 2-character suffix for unique file identifier. 

Table B-27. INFORM Macro Parameter Packet Format Suffix* 

0 Request Code | Length FL 
2 Return Information CR 
4 
6 Count Address IN 


Description 
Request Code: INFORM=05 

Length, number of words in the parameter packet: 04 

Return Information 

Not used 

Segment Tag 


Count address: address of a one-word location containing a count of the number of requests 
not known to have completed at this time. 


*The 2-character suffix for unique file identifier. 
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Tabie B-28. SETIF Macro Parameter Packet Format Suffix 


Request Code | Length FL 


2 Return Information CR 
4 S TAG 
6 Buffer Address IN 


Description 


Request Code: SETIF=45 


Length, number of words in the parameter packet: 04 


Return Information 


Not used 


Segment Tag 


Buffer Address: address of a one-byte buffer containing the data to be transferred. 


*The 2-character suffix for unique file identifier. 
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Table B-29. DELAY Macro Parameter Packet Format. Suffix** 


Request Code | Length FL 


Oo fF HO OO 


Return Information CR 
BT 
Delay Address IN 


Description 


Request Code: DELAY=04 

Length, number of words in the parameter packet: 04 
Return Information 

Not used 

Break Flag (B) 

O = no delay break 

1 = delay to be broken on any service request completion 
Type Fiag (T) 

O = delay in seconds 

1 = delay in cycles* 


Segment Tag 


Delay Address: address of a one-word buffer containing the duration of the delay in seconds 
or cycles* (see Type Flag). 


*Cycle equals 50.2 milliseconds. 


**The 2-character suffix for unique file identifier. 
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Table B-30. HALT Macro Parameter Packet Format Suffix* 


0 Request Code Length FL 


2 Return Information CR 


re Hee eet she gn 


Description 


Request Code: HALT=64 


Length, number of words in the parameter packet: 02 


Return Information 


*The 2-character suffix for unique file identifier. 


Table B-31. EHALT Macro Parameter Packet Format Suffix* 


Request Code Length FL 


Return Information CR 


Description 


Length, number of words in the parameter packet: 02 


Return Information 


*The 2-character suffix for unique file identifier. 
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Table B-32. ABEND Macro Parameter Packet Format Suffix* 


Request Code | Length FL 


0 
2 Return Information CR 
4 
6 Buffer Address IN 
Description 
Request Code: ABEND=75 
Length, number of words in the parameter packet: 04 
Return Information 
Segment Tag 
Buffer Address: address of location containing the completion code. 
*The 2-character suffix for unique file identifier. 
Table B-33. TIME Macro Parameter Packet Format Suffix* 
0 Request Code | Length FL 
2 Return Information ; CR 
4 
6 Buffer Address IN 


Description 
Request Code: TIME=73 

Length, number of words in the parameter packet: 04 
Return Information 

Segment Tag 


Buffer Address: address of location containing the time 


*The 2-character suffix for unique file identifier. 
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Table B-34. SDATE Macro Parameter Packet Format Suffix* 


Request Code | Length FL 


2 Return Information CR 
4 D | S$ TAG BT 
6 Buffer Address , IN 


Description 


Request Code: SDATE=74 


Length, number of words in the parameter packet: 04 


Return Information 


Date Flag 


j=) 


Calendar date 


1 = Julian date 


Segment Tag 


Buffer Address: address of location containing the date 


*The_2-character suffix for unique file identifier. 


Table B-35. JDATE Macro Parameter Packet Format Suffix* 


Request Code Length FL 


Return Information CR 


D | S TAG BT 


Description 


Request Code: JDATE=66 


Length, number of words in the parameter packet: 04 


Return Information 


Date Flag 
QO = Calendar date 


Julian date 


Segment Tag 


Buffer address: address of location containing the date 


*The 2-character suffix for unique file identifier. 
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Table B-36. CONSOLE Macro Parameter Packet Format 


Request Code | Length 


2 Return Information 
4 
6 Buffer Address 
8 
10. Reply Address 


Description 


Request Code: CONSOLE=01 


Return Information 
Segment Tag 


Buffer Address: address of location containing message 


Segment Tag 


Reply Address: address of location containing reply message. 


*The 2-character suffix for unique file identifier. 


Length, number of words in the parameter packet: 04 (without reply) or 06 (with reply) 


Suffix* 
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INTRODUCTION 


Of the various classes of possible errors associated 
with a service request, the operating system’s error 
recovery program is concerned with only one 
particular class: the input/output hardware 
malfunctions. Attempted recovery from these 
input/output hardware malfunctions will be 
performed for all levels of input/output coding by 
default; however, at the physical level it may be 
bypassed if specified. 


lf an error proves to be irrecoverable, information 
describing the error is returned to the user’s request 
or command block (Table C-1) and then, normally, 
the job is aborted. However, if the operand, 
ERRCOMP=YES had been coded in the original 
request, control is returned so that the user may 
either ignore the error or attempt to process it 
himself. 


In addition to its basic task of attempting to recover 
from errors, the error recovery program is also 
responsible for handling certain exceptional non-error 
situations, such as EOF detection and indication. 


TYPES OF ERROR 


The following major categories of error are handled 
by the error recovery program. 


INTERVENTION REQUIRED 


When operator intervention is required, a console 
message is issued. Once the operator has serviced the 
device, he responds to the message indicating either 
to continue processing or to return control to the 
user. The MRX/OS Messages manual contains the 
operator console messages. 


C. ERROR RECOVERY 


ERRORS REQUIRING RETRIES 


Input/output requests completed but including 
specific types of errors are retried a given number of 
times. If the error persists, a message is typed on the 
operator’s console. The operator response indicates 
either to retry the request another specific number of 
times or to return the error condition indication to 
the user program. If one of the retries succeeds, a 
normal completion indication is returned to the user 
program as though no error had occurred. 


CONDITIONS OF UNCERTAINTY 


There are certain error conditions where the error 
recovery program is unable to perform accurate error 
recovery, or any error recovery at all; for example, 
not being sure where magnetic tape is positioned. 


Although the error recovery program checks all 
defined hardware conditions, it is not inconceivable 
that an undefined condition from a non-supported 
hardware device might arise; in this case the error 
recovery program is unable to process it. 


With regard to the first example, it should be noted 
that although the error recovery program checks all 
defined hardware conditions, it is not inconceivable 
that an undefined condition might arise; in this case 
the error recovery program is unable to process it. 


When error conditions of this kind occur, a message is 
typed on the operator’s console. If the message 
requires a response and the operator chooses to 
continue, the user may either gain or lose 
information. If the message does not require a 
response, the request is routed back to the user with a 
return code. 


IMMEDIATE IRRECOVERABLE CONDITIONS 


An example of an error so classified is that of 
magnetic tape running off the end of the reel. In 
situations such as this, a console message is typed and 
the request is routed back to the user with a return 
code. 


CONDITIONS THAT DO NOT REQUIRE 
RECOVERY 


Certain conditions routed to the error recovery 
program are considered to be normal completions and 
do not require the issuance of any return codes or 
error messages. Two examples are these: 


@ a parity error while spacing magnetic tape 
(no recovery is needed because tape is 
properly positioned) 


e detection of an end-of-file condition 
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ERROR LOGGING 


Error logging is an integral part of the operating 
system. The error log file, which is built at system 
generation time, consists of forty-byte records (Table 
C-2). 


Records of error conditions and retries are 
maintained in the two error flag bytes and two error 
counters, respectively (located in the extension area 
of each unit table entry). The bits of the error flag 
bytes represent the error conditions that can occur. If 
multiple errors occur, bits are set as the error 
conditions are detected. 


The error counters are incremented by 1 whenever a 
retry error condition occurs. Each error counter can 
contain more than one error condition. 


Condition 


EOA on this disc request 


Channel 12 on the printer carriage 
control tape 


This request was not processed be- 
cause an exception condition 
occurred on a previous request and 
the file has not been reset 
Disc EOF 
Unit down 

Card reader EOF 


Invalid function code in command 
program 


Channel 9 on the printer carriage 
control tape 


A Remove request removed this 
request 


Length error. A record was read 
which was longer than the buffer 
space provided for it 

Tape mark sensed on any Read 
operation not including Search 
command 
An ASKATT request is being re- 
jected because an ASKATT is 
already pending against the device 


Error status indication returned 
from an 1/O operation 


_ Operation timed out 


Unsolicited attention set 


or Restore 

No error recovery for device 
Invalid function code in BIO macro 
Invalid block number 

Invalid byte count 

Invalid CNTRL request 

No FDT 

Usage error 

Operation to locked file 


Invalid sequence of operations to 
a device 


Subfunction field error 

Invalid position (to magnetic tape 
file that is not maintaining block 
numbers) 


EOF on a read to a bypassed file 


Invalid unit ordinal on privileged 
PIO request 


Bad I/O status indication from Seek 


Table C-1. 1/O Error Recovery Information 


Hexadecimal PCB/Request| Message 


Status FDT  |Block Return Code 
Completion| Return | information | Displayed 
Code i Field On Console 
fi . - 
0 0002 A002 [see 
5002 0002 co002 002 
0 0003 A003 poe | 
, 4 ~ - 
0 0006 A006 te 
5006 _ C006 

5010 Ee C010 

503F 003F CO3F Fo =| 
a fl ~ hak 
ee 


*Number of retries automatically performed by Error Recovery before completion is declared. 


Bonkole Error Log 
Message No. of Record 
Reply Retries* Written 
wis 
BO | 
a (ee ea (ns Se 
a ae ee 
j oe 
cee ec ee ee ee ee 


as 
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DISC 
Timeout 


Command reject 


Seek incomplete 


Not on fine 


File unsafe 


Pack change 
Status not valid 
Command early 
Unsolicited Attention 
Catastrophic error 
Missed window 


IFA window 


Track boundary 


Read Write terminate 
Burst check 

Lost data 
No sync compare 


Write operation issued to a drive 
in read only mode 


End of cylinder 


Invalid seek address 


Search failed (arm mispositioned) 


Search failed (no record found) 


PRINTER 
Command reject 


1/O Channel error 


Data check 
Not ready 
| Bus out check 


Catastrophic error 


Both channel 9 and 12 on the 
! printer carriage control tape 
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Table C-1. 1/O Error Recovery information (Continued) 


Hexadecimal 
Status 
Completion 


FDT 
Return 
Information 


0050 


0051 


0054 
0055 
[8 


PCB/Request 
Block Return 
Information 


Cc04D 


CO50 
C051 
C052 


Message 
Code 
Displayed 
On Console 


Error Log 
Record 
Written 


Console 
No. of 
Retries 


Message 
Reply 


Y 


~ 
2 


Y/N 


Y/N 


heal 


<|< 
| | 


Y/N 


Y/N 


Y/N 


E 


Y/N 


Table C-1. 1/O Error Recovery Information (Continued) 


Hexadecimal PCB/Request| Message 

Status FDOT Block Return Code Console 
‘Completion Return Information | Displayed | Message 
Code Information Field On Console Reply 


Condition 


No. of 
Retries 


CARD READER 
Catastrophic error 
‘Command reject 
Not ready 
Busy 
Feed check or jam 
Read check 
Data check (illegal EBCDIC char.) 
Time out 
Unsolicited attention 


Initial selection error 


CARD READER PUNCH 
Catastrophic error 
Command Reject 


‘| Not ready 


Busy 

Feed check or jam 
Data check (illegal EBCDIC char.) 
Read check 

Time out 
Unsolicited attention 


Initial selection error 


C089 


Punch check 


MAGNETIC TAPE 
| Command reject (read reverse) 
| Command reject (protected tape) 


Intervention required (without 
equipment check) 


Intervention required (with 
equipment check) 


Bus out check (on command) 


Bus out check (on data) 
Equipment check (Read Write reg.) 
Equipment check (Write register) 


Equipment check (Read register) on 
data 


Equipment check (Read register) 
| on command 


| Equipment check (Delay register) 
on data 


Error Log 
Record 
Written 


Condition 


Equipment check (Delay register) 
on command 


Data check (Write) 
Data check (Write File Mark) 


Data check (muttiple track error 
on read) 


Data check (single track error on 
read) Includes preamble and post - 
amble errors 


Data check (phase track in error 
and VRC without Read Write 
register error) 


Data check (Erase) 
Over run 


Word count zero (Write Command 
Count # 0) 


Not capable 
Backspace into BOT 
Reverse Read command at BOT 
EOT during any write operation 
Unsolicited attention 

Time out 

Undefined IOC error 

Internal recovery error No, 1* 
ators recovery error No, 2* 


Internal recovery error No, 3* 


iss channel error 

Wrong address-in channel error 
Control check channel error 
Transmission check channel error 


Zero byte count 


*Catastrophic error. 
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Table C-1. 1/O Error Recovery Information (Continued) 


Hexadecimal 
Status 
Completion 
Code 


50A9 


50AA 


50AB 


50AC 


50AD 


Information 


FDOT 
Return 


O0A9 


OOAA 
OOAB 
OOAC 


O00AD 


PCB/Regquest| Message 

Block Return Code 

Information | Displayed 
Field On Console 
COBO OBO 
~ coBt 0B1 
AOB2 a - 

: 

: 
COB6 OB6 
COB7 0B7 
COB8 OB8 
COBB OBB 


Error Log 
Console Record 
Message Written 


Reply 


S15 
zZ\2 


< 
— 
2 


Y/N 


2 


Y/ 
Y/N 


= 
2 


Y/N 


Table C-2. Error Log Record 


0 ID DATE/TIME 
2 DATE/TIME DATE/TIME 
4 DATE/TIME DATE/TIME 
6 DATE/TIME DATE/TIME 
8 DATE/TIME DATE/TIME 
10 DATE/TIME - DATE/TIME 
12 DATE/TIME PROCESSOR 
14 DEVICE ADDR CMD IN ERROR 
16 STATUS STATUS 
18 ER FLAG BYTE 0 ER FLAG BYTE 1 
20 ERROR COUNTER 1 ERROR COUNTER 2 
22 ERROR COUNTER 3OR CYLINDER ERROR COUNTER 4 OR HEAD 
24 VOL ID VOL ID 
26 VOL ID VOL ID 
28 VOL ID VOL ID 
30 SENSE SENSE 
32 SENSE SENSE 
34 SENSE SENSE 
36 
38 RECORD SEQ. NUMBER RECORD SEQ. NUMBER 
Bytes Mnemonics Description 
0 iD Identification of the record. The vatue of this field is as follows: 
Hex Value Explanation 
01 from disc error recovery 
02 from tape error recovery 
03 from card reader error recovery 
04 from card reader punch error recovery 
05 from printer error recovery 
06 from logical communications error recovery 
07 from error correction code feature (optional) 
1-12 DATE/TIME The date and time which are supplied by the Exec are in a binary format as follows: 
Byte Explanation 
1 unused 
2 year 
3 , month 
4 day 
5 hour 
6 minutes 
7-10 seconds 
11-12 hardware clock 
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Table C-2. Error Log Record (Continued) 


Bytes Mnemonics Description 
13 PROCESSOR Processor state which the device uses. The processor codes are as follows: 
Hex Code Processor 

08 zero 

04 one 

02 two 

01 three 
14 DEVICE ADDR The physical device address. The physical device address for disc is the cable address (not the 

plug adclress). 

15 CMD IN ERROR The command code that the driver is attempting to execute when the error condition occurs. 
16-17 STATUS The two bytes of hardware status indication. 
18-19 ER FLAG BYTE 0 &1 Flag bits set by error recovery modules when the different error conditions occur. The two 


flag bytes are described as follows: 


Magnetic Tape 


Flag Byte O 
Bit Explanation 
0 intervention required 
1 bus out check 
2 equipment check (register parity) 
3 equipment check (internal counter) 
4 data check 
5 over run 
6 word count zero 
7 preamble/postamble error 
Flag Byte 1 
Bit Explanation 
O timeout error 
1 ISS channel error 
2 wrong address-in channel error 
3 control check channel error 
4 transmission check channel error 
5-7 unused 
Disc 
Flag Byte 0 
Bit Explanation 
O command early 
1 timeout 
2 disc arm mispositioning 
3 unused 
4 read/write terminate 
5 catastrophic error 
6 lost data 
7 no sync compare 
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Table C-2. Error Log Record (Continued) 


By tes Mnemonics 


Flag Byte 1 


iv] 
> 


2S ESS So 


Flag Byte 0 


is] 
= 


WORN =O | 


Flag Byte 1 


Bit 
0-7 


Flag Byte O 


Oo 1a 
& |Z 


“OO C1 = 


Flag Byte 1 


ALon-o |g 
ot 


? 
N 


Description 


Explanation 


third revolution sync find 
seek incomplete 

file unsafe 

missed window 

burst check 

end of cylinder 

disc write current 

busy 


Card Reader and Reader Punch 


Explanation 


timeout 

busy 

ISS channel! error 
catastrophic error 
punch check 
command reject 

read check 

card feed check or jam 


Explanation 


unused 


Printer 


Explanation 


timeout 

unused 

bus out check 

data check 

invalid sense information 


Explanation 


ISS error 

unused 

wrong address in initial selection or address/status parity 
no request in SIO poll sequence request 

control check 

data transmission check 

unused 


Note: The printer hardware status bytes that are written in the error log file represent 
all of the conditions that occurred while printer error recovery was in progress 
for a given error. Therefore, if a channel error occurs during recovery procedures, 
it will appear in the two hardware status bytes. 


Bytes 


20 


21 


22 


23 


24-29 


30-35 


36-37 


38-39 
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Mnemonics 


ERROR COUNTER 1 


ERROR COUNTER 2 


ERROR COUNTER 3 
or CYLINDER 


ERROR COUNTER 4 
or HEAD 


VOLID 


SENSE 


Table C-2. Error Log Record (Continued) 


Description 


The following errors use Counter 1: 
1. Card Reader and Card Reader Punch Error Recovery error conditions. 
2. Disc Error Recovery error conditions except search failures. 


3. Magnetic Tape Error Recovery for user request error condition. 


The following errors use Counter 2: 
1. Disc Error Recovery for a search failure. 


2. Magnetic Tape Error Recovery for recording the number of erase operations 
performed during the recovery of a write operation. 


Error Counter 3 is incremented by the Magnetic Tape Error Recovery for positioning 
errors. Or, the disc’s cylinder number is extracted from the seek argument of the first 
command word in a command program. If the first command word is not a seek, the 
cylinder number is not supplied. 


Magnetic Tape Error Recovery uses Counter 4 as a record counter. Bits 0-3 are used 
when positioning forward and bits 4-7 are used when positioning backward. The 
disc's head number is extracted from the seek argument of the first command word 
in a command program. If the first command word is not a seek, the head number is 
not supplied. 


Volume ID. This field applies only to disc. 


From one to six sense bytes depending on the type of device. See the associated hardware 


specification for the bit positions and their meanings. 
Unused. 


Record sequence number. 


D. GAP SPECIFICATIONS 


Table of Gap specifications to be used with the COMMAND/OPCODE=DCWRIT macro when working 
with fixed record lengths (and no key fields). 


Record Size Number of 
in Bytes Records in Track GAP (Inverted Hex) 


3521 — 7294 
2299 — 3520 
1694 — 2298 
1333 — 1693 
1093 — 1332 
922 — 1092 
794— 921 
695 — 793 
616— 694 
551— 615 
497 — 550 
451— 496 
412— 450 
378 — 411 
348 — 377 
322 — 347 
299 — 321 
277 — 298 
276 

258 

241 

226 

211 

199 

187 

176 

166 

157 

148 

139 

132 

125 

118 

112 

106 


SOON OA RWNHD = 


D-1 


| RO DATA DATA 
HOME NT 
ADDRESS saat FIELD COUNT FIELD SEL 
5+4 (BURST) 9+4 (BURST) VARIABLE 9+4 (BURST) 

BYTES BYTES (8+4) TO BYTES 


FULL TRACK BYTES 


_—— GAP BIT CONFIGURATION ~_~— 


nen 
_ 
— 
—_— 
— 


| BIT RING 
VARIABLE AREA VFO AREA 5 BYTES pyle SYNC AREA 
1 BYTE 


ONES ONES SEE 
5 BITS MISSING 5 BITS MISSING TRACK 
CLOCK PULSES CLOCK PULSES FORMAT 
ee a 
° 111111<19;)171397111141 


F = FLAG BYTE 
CC = CYLINDER NUMBER IN BINARY 
HH = HEAD NUMBER IN BINARY 
R = TRACK RECORD NUMBER IN BINARY , 
K = KEY FIELD LENGTH IN BINARY : 
HA RO COUNT RO DATA 
DD = DATA FIELD LENGTH IN BINARY Svue SYNC SYNC avi 
F8 = FIRST (CYCLIC BURST) BYTE aYTE Ae BYTE BYTE 
$8 = SECOND (CYCLIC BURST) BYTE 
IC = INDICATOR BYTE 
BC = BIT COUNT BYTE 
GO = 41 BYTES + 0.043 X (Ky +D,)* "310 "10 510 410 1019 
G2 = 41 BYTES 
Laine teal ooo00110 foooo101f foooorcom foooorr1of fooooro1of fooo01 001 


— * BURST CHECK BYTES NOT INCLUDED 
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F. INDEX—BLOCK SIZE FOR INDEXED FILES 


There is a minimum index block size for every 
indexed file depending on key size and file size. The 
user may utilize any index block size larger than the 
minimum, if he has memory space for a larger index 
block. The larger the index block the better retrieval 
becomes on random processing. If the user goes 
below the minimum index block size there is the 
possibility of not being able to create the file size as 
planned. 


When planning the creation of indexed files, the user 
must decide whether he wants to process the 
directory-directory, which resides on mass storage, in 
amain memory buffer. This option speeds up random 
processing, but requires extra space for the buffer. If 
the mode of processing is with a main-memory buffer 
there is a well-defined optimum index block size 
which .minimizes memory space for the index buffer 
and directory-directory buffer. 


Once the user has determined his mode of processing, 
Table F-1 is used to determine minimum-keys/block 
and Table F-2 is used to determine optimum 
keys/block. Note that in using Table F-1 and Table 
F-2, the larger of the two values in the file size is the 
determining factor. Also note that these tables were 
computed for consistency for maximum key size and 
one million records as the upper limit. There will be 
some index block sizes generated that exceed one 
track in number of bytes. This exceeds the system 
limit for block sizes. The user will have to choose a 
smaller key size or smaller file size. 


The keys/block is entered in the Control Language 
//DEFINE statement along with key size. The 
corresponding minimum or optimum index block size 
can be calculated from Table F-3. The resulting index 
block size is then entered in the COBOL source 
program via the INDEX-BLOCK Clause. 


If the user has determined to calculate the optimum 
keys/block and optimum index block size, Table F-4 
is used to calculate the number of bytes for the 
main-memory buffer for the directory-directory 
entries. 


The user must be careful not to exceed the file 
maximum at creation time when using the optimum 
block size -— when he utilizes the main-memory 
buffer to hold the directory-directory entries for 
random processing, the buffer would not be able to 
hold all the entries, thus writing over the user 
program. Thus, when choosing an index block size 
other than the optimum and the main-memory buffer 
is used to process the directory-directory entries, the 
buffer size should be the size of the index block, as 
the system checks for overflow at creation time. 


If the user wishes to calculate keys/block based ona 
different file maximum than given in Tables F-1 and 
F-2, the following algorithms, along with Table F-5, 
can be used to compute minimum and optimum 


keys/block. The constants Ko and Km are taken from 
Table F-5 based on key size. 


Optimum (OKB) | 3 | = 
Minimum (MKB) -| 3 | ie 


FS = Maximum File Size 


NOTE: | = Round up if result not 
whole integer. 
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Table F-1. Minimum Keys/Block 


Key Size in Bytes 


Blocks in File 


0 - 5,000 
5,000 - 10,000 
10,000 - 15,000 
15,000 - 20,000 
20,000 - 25,000 
25,000 - 30,000 
30,000 - 35,000 
35,000 - 40,000 
40,000 - 45,000 
45,000 - 50,000 
50,000 - 60,000 
60,000 - 70,000 
70,000 - 80,000 
80,000 - 90,000 
90,000 - 100,000 
100,000 - 125,000 
125,000 - 150,000 
150,000 - 175,000 
175,000 - 200,000 
200,000 - 250,000 
250,000 - 300,000 
300,000 - 350,000 
350,000 - 400,000 
400,000 - 450,000 
450,000 - 500,000 
500,000 - 600,000 
600,000 - 700,000 
700,000 - 800,000 
800,000 - 900,000 
900,000 - 1,000,000 


Blocks in File 


0 - 5,000 
5,000 - 10,000 
10,000 - 15,000 
15,000 - 20,000 
20,000 - 25,000 
25,000 - 30,000 
30,000 - 35,000 
35,000 - 40,000 
40,000 - 45,000 
45,000 - 50,000 
50,000 - 60,000 
60,000 - 70,000 
70,000 - 80,000 
80,000 - 90,000 
90,000 - 100,000 
100,000 - 125,000 
125,000 - 150,000 
150,000 - 175,000 
175,000 - 200,000 
200,000 - 250,000 
250,000 - 300,000 
300,000 - 350,000 
350,000 - 400,000 
400,000 - 450,000 
450,000 - 500,000 
500,000 - 600,000 
600,000 - 700,000 
700,000 - 800,000 
800,000 - 900,000 


900,000 - 1,000,000 


101 


Table F-2. Optimum Keys/Block 


100 
103 


102 
105 


103 
107 


Key Size in Bytes 


29 30 30 
32 32 33 
34 34 35 
36 36 37 
37 38 38 


50 51 51 
54 55 55 
58 58 59 
61 61 62 
63 64 65 
68 69 70 
73 73 74 
76 77 78 
80 81 81 
83 84 85 
86 87 88 
91 92 93 
96 97 98 


100 102 102 
105 106 106 
108 109 110 


101 
105 
110 
113 
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Table F-3. Optimum or Minimum Index Block Size 


(10) (OKB) (KS+4) 


Optimum block size 9 


OKB = Optimum keys/block 


KS = Key size 


(10) (MKB) (KS+4) 
9 


Minimum block size 


MKB = Minimum keys/block 
KS = Key size 


Round up if result not whole integer. 


Table F-4. Bytes Required in Buffer for Directory-Directory Entries 


Usage = ores 10" = US 


ba eS ae _f_us - 
Number keys/primary index block (5 | NKP 


, _| —YS_ ]_ 
Number keys/directory block las | NKD 


Total number keys represented/ 


directory block = (NKP) (NKD) NKRD 
Number entries in _}file size _ 
Directory-directory block {| NKRD |uko 


Number of bytes required for 
buffer for directory-directory = 10+ (KS+2) (NKDD) 
entries 


nore |. Round up if result not whole integer. 
[ |= Round down if result not whole integer. 


WON] 00 MONOTAWNI] 


NN MN a = wa = 2 = 
AN] C2 DAN OG A 


24 


Table F-5. Constants for Alternate Algorithm 


F-5 


INDEX 


ABEND macro 
ACCEPT macro 


Access 
random 
sequential 
Action macros 
Add mass storage space 
ALLOC macro 


Allocate space 
Assumed block number 
Attribute element 


BDT 
sequential files 
relative files 
indexed files 
Bit significance 
BLKNUM parameter 
BLKSIZ parameter 
Block !/O 
coding 
declarative macro 


device control commands 


error processing 
file control 
general description 
macros 
CNTRL 
POSITN 
READ 
RESET 
STATUS 
TYPE 
WRITE 
positioning 
program 
reading 
request termination 
rules 
sense information 
space management 
writing 
BREAK parameter 
BUFADR parameter 
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7-31 
7-7,15,24,27 


Buffer description table 
general description 
indexed files 
relative files 
sequential files 

BUFSIZ parameter 


Catalog elements 
attribute 
continuation 
name 


space 
volume 
CATALOG parameter 
Central catalog 
CHAIN parameter 


Change current block number 
Close file for data transmission 
CLOSE macro 


Close volume 
CLOVE macro 


CNTBUF parameter 
CNTRL macro 


CNTSIZ parameter 
COMMAND macro 
basic data channel 
DCABLE 
DCJUMP 
DCREAD 
DCSEEK 
DCSRCH 
DCWRIT 
RESTORE 
Command program 
Common stored data format 
CON parameter 


Console communication macros 


CONSOLE 


MESSAGE 
CONSOLE macro 


Index-1 


CONTROL parameter 
Control program macros 

ABEND 

ACCEPT 

DELAY 

DISPLAY 

EHALT 

GETCOM 

HALT 

INFORM 

JDATE 

MEMLIM 

POST 

RPOST 

SDATE 

SETCOM 

SETIF 

TIME 

WAIT 


Control program services 
finding partition size 
inter-step and control language 

communication 

reading data from //PAR cards 
service request control 
writing to SYSOUT 

CP parameter 

CPADR parameter 

Create communication byte 

CSD parameter 

CWADR parameter 

CYCLES parameter 


Data macros 

Data structures 
DATACYL parameter 
DATATXT parameter 
DATBUF parameter 


DATABUF1 parameter 
DATABUF2 parameter 
DATSIZ Parameter 


DATSIZ1 parameter 
DATSIZ2 parameter 

Define file label 

Defining and opening devices 
DEFLB macro 

DELAY macro 


Device and file type 
Device control commands 
DEVTYP parameter 
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Disc catalog 
central 


pack 
Disc track format 
DISPLAY macro 


EBCDIC parameter 
EHALT macro 
ELEMENT parameter 


End conditions 


EOF 


ENDAD R parameter 
ERRCOMP parameter 


ERROPT parameter 

Error log record 

Error logging 

Error processing 

Error recovery 
types of errors 
intervention required 
retries 
information 
uncertain conditions 
irrecoverable conditions 
error logging 

EXCP instruction 

EXCP macro 

Expand from communication byte 

EXPND macro 


FDT 


FIELD parameter 
File control 
general description 
macros 
CLOSE 


CLOVE 


OPEN 
File description table 


File label (tape) 
File organization 
FILENAM parameter 
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2-2,3;A-1, 
4,7 
2-2,3;A-1,2 
E-1 
5-2:7-1,35 


7-10,12 
7-1,37;B-36 


3-4:7-3, 
5 thru 10,12 
thru 15,21,23, 
30 thru 36; 
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2-12,13 thru 
19;3-4;7-2 
7-27,28,30 
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FILEORG parameter 
Files 

indexed 

relative 

sequential 
FILESIZ parameter 
FILETYP parameter 
Fixed length records 
FUNCTN parameter 


GAP parameter 

Gap specification 
Generation of reply buffer 
GETCOM macro 


HABUF parameter 

HALT macro. 

Hardware control operation 
HASIZ parameter 


IDENT parameter 


Identify partition limit 
INDCYL parameter 
Index block size 
Indexed files 

INDSIZ parameter 
INFOADR parameter 


INFORM macro 


Input/output action 
Input/output levels 

logical 

block 

physical 
Interaction of Data Management 

and Control Language 

I/O service macro (LABRTN) 
lOTYP parameter 


JDATE macro 


KEY BUF parameter 
KEYSIZ parameter 


LABDEF parameter 
LABDEF1 parameter 
LABDEF2 parameter 
Labels 

tape 

disc 
LABRTN macro 
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7-28 ,29 
7-1,36;B-36 
7-13 

7-28 ,29 


7-3 thru 10, 


12 thru 15,21 


7-35 


7-9,32,33, 
36,37 
5-1;7-1,31; 
B-33 

7-22 


1-1 
1-1, 
1-1, 


6-1 
7-1,9;B-16 
7-7,8 


7-1,37;B-38 


7-28,29 
7-3,4,28,39 


7-1,33; 


LIST parameter 


LOCK parameter 


Logical 1/O 


Macro expansions | 


Macros 
ABEND 
ACCEPT 
ALLOC 
CLOSE 
CLOVE 
CNTRL 
COMMAND 
CONSOLE 
DEFLB 
DELAY 
DISPLAY 
EHALT 
EXCP 
EXPND 
GETCOM 


-HALT 
INFORM 
JDATE 
LABRTN 
MEMLIM 


MESSAGE 
OPEN 


PCB 
POSITN 


POST 
PURGE 
READ 


RESET 


Index-3 


7-3 thru 10, 
12 thru 15,21, 
30 thru 36;B-3 
7-8 

1-1 
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Macros (continued) 
RPOST 


SDATE 
SETCOM 


SETIF 
STATUS 


TIME 
TYPE 


WAIT 
WRITE 
MEMLIM macro 


MESSAGE macro 

MODE parameter 

MSC parameter 

MULTBLK parameter 
Multi-volume file processing 


Name element 
OPCODE parameter 
OPEN macro 

OPER parameter 


Pack catalog 
PAIRED parameter 


Parameters 
BLKNUM 
BLKSIZ 
BREAK 
BUFADR 
BUFSIZ 


CATALOG 
CHAIN 


CNTBUF 
CNTSIZ 
CON 
CONTROL 


CWADR 
CYCLES 
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2-3,4;A-5 


7-24,27 
thru 30 
3-3:6-1; 
7-1,6;B-12 
7-11,12,14 


2-3;A-1,2 
7-5,6 


7-11,12,13 
7-3 
7-31 


7-7,15,24,27 


7-15,24,27, 
28 

7-3,5,6 
7-24,27,28, 


Parameters (continued) 


Index-4 


DATATXT 
DATACYL 
DATBUF 


DATBUF1 
DATBUF2 
DATSIZ 


DATSIZ1 
DATSIZ2 
DEVTYP 
EBCDIC 
ELEMENT 
ENDADR 
ERRCOMP 


ERROPT 
FIELD 
FILENAM 
FILEORG 
FILESIZ 
FILETYP 
FUNCTN 
GAP 
HABUF 
HASIZ 
IDENT 


INDCYL 
INDSIZ 
INFOADR 


lOTYP 
KEY BUF 
KEYSIZ 
LABDEF 


LABDEF1 
LABDEF2 
LIST 


LOCK 
MODE 
MSC 
MULTBLK 
OPCODE 


OPER 
PAIRED 


7-3 
7-10,12,28, 


thru 10, 
12 thru 15, 
21,23,30 
thru 36;B-4 
4-3;7-23 


12 thru 15,21 
7-3,4 


7-28,29 
7-3,4,28,39 
7-5,6,7 
7-3,4 

7-3,4 

7-3 thru 10, 
12 thru 15, 
21, 30 thru 
36;B-3 

7-8 
7-30,37,38 
7-2 


Parameters (continued) 


RETURN 


REWIND 


VERIFY 
PARNUM parameter 
PCB 

general description 

macro 

parameter 
Peripheral device hardware codes 
Physical 

command block 

control block 

request termination 
Physical 1/O 

coding 

error processing 

general description 

macros 
EXCP 
PCB 

operation 

overlap 

program 

request termination 

restrictions 
POSITN macro 


Post code for Control Language 
POST macro 


Priority 

Processing considerations 
end conditions 
multi-volume files 
priority 
request overlap 


7-30,32 
4-1:7-3 thru 
10,12 thru 15, 
21,23,32 thru 
36;B-4 

7-7,8 

7-31 


WN — 
OO 


PURGE macro 


Random access 
READ macro 


Reading data from //PAR cards 
Read //PAR card 
Records 

fixed length 

variable length 
RECSIZ parameter 
Relative files 
Release disc file space 
Report of status 
REQADR parameter 
REOCNT parameter 
Request 

overlap 

termination 
Reset exception conditions 
RESET macro 


Retrieve 

system date 

time of day 
Return file label information 
RETURN parameter 


Returned information format 
REWIND parameter 
RPOST macro 


SDATE macro 
SECONDS parameter 
SEEK parameter 
Sense information 
Sequential 

access 

files 
Service request mechanism 

complete bit 

CONTROL 

end flag 

error flag 

function code 

instruction 

length 

linkage 

return code 

return information 
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3-3;6-1;7-1, 
2,5;B-11 


7-9 

4-1:7-3 thru 
10,12 thru 15, 
21,23,32 thru 


7-31 
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Set up message format 
SETCOM macro 


SETIF macro 


Sharing 

an EXCP 

a PCB 
SIZERR parameter 
SKIP parameter 
Space element 


Space management 
general description 
macros 

ALLOC 


EXPND 
PURGE 


SPREAD parameter 
Standard system suffixes 
STATUS macro 


Status word 
data channel 
disc channel 
STRIP parameter 
Suspend program execution 


B-4 
3-2;7-1,15; 
B-17 


Tables 
FDT 


BDT 


Tape labels 
volume 
file 
Terminate program 
TIME macro 
TYPE macro 


UNORD parameter 
USAGE parameter 


Variable length records 
VERIFY parameter 
Volume element 
Volume label 

disc 

tape 


Wait for service request 
completion 

WAIT macro 

WRITE macro 


Write message on SYSOUT 
Writing to SYSOUT file 


Index-6 


2-12,13 thru 
19;3-4:7-2 
2-12,20 thru 
34 


7-30 
5-1;7-1,30; 
B-30 


COMMENTS FORM 


SLIT TE TSE IA ISS SE A Sa a OLE RENO BON Ty EER IN Det ETS OF TN EE 
MRX/OS Control Program and Data Management Services 
Extended Reference Manual (2200.002) 


Please send us your comments, to help us produce better publications. Use the space below to 
qualify your responses to the following questions, if you wish, or to comment on other aspects of 
the publication. Please use specific page and paragraph/line references where appropriate. All 
comments become the property of the Memorex Corporation. 


Yes No 
) Is the material: 

Easy to tinderstand? 1.5 2 6-42 eee a ee ew ee O 0 
Conveniently organized? 2... 1. ee te ee es O 0 
CONIBIBIER 2 22 rn ee a WR ee Rh ee ee aS Oo O 
Well illustrated? -s. sae a-0 Spake AS ee Pa Wa es Bes a) 0 
Accurate?’ 3% <-ola we aol ee ae oe ee ew Be ae 0 O 
Suitable for its intended audience?............0:. Ken ee old 0 0 

oO O 


Adequately indexed? ....... 2. eee eee ee ee es 


e For what purpose did you use this publication? (reference, general interest, etc.) 
e Please state your department's function: 


e Please check specific criticism(s), give page number(s), and explain below: 


O Clarification on page(s) 
Addition on page(s) 


Deletion on page(s) 


o000 


Error on page(s) 


ee A 


mm a A TT 


First Class 


Permit No. 14831 


Minneapolis, 
Minnesota 55427 


a 


= 
Ze 

= Business Reply Mail 
a, 


>) No Postage Necessary if Mailed in the United States 


Postage Will Be Paid By 


) U) | Memorex Corporation 


Midwest Operations — Publications 
8941 Tenth Avenue North 
Minneapolis, Minnesota 55427 


Thank you for your information.......... 


Our goal is to provide better, more useful manuals, and your 
comments will help us to do so. 


stata anne S Memorex Publications 


